PyXR

c:\python24\lib \ doctest.py

0001 # Module doctest.
0002 # Released to the public domain 16-Jan-2001, by Tim Peters (tim@python.org).
0003 # Major enhancements and refactoring by:
0004 #     Jim Fulton
0005 #     Edward Loper
0006 
0007 # Provided as-is; use at your own risk; no warranty; no promises; enjoy!
0008 
0009 r"""Module doctest -- a framework for running examples in docstrings.
0010 
0011 In simplest use, end each module M to be tested with:
0012 
0013 def _test():
0014     import doctest
0015     doctest.testmod()
0016 
0017 if __name__ == "__main__":
0018     _test()
0019 
0020 Then running the module as a script will cause the examples in the
0021 docstrings to get executed and verified:
0022 
0023 python M.py
0024 
0025 This won't display anything unless an example fails, in which case the
0026 failing example(s) and the cause(s) of the failure(s) are printed to stdout
0027 (why not stderr? because stderr is a lame hack <0.2 wink>), and the final
0028 line of output is "Test failed.".
0029 
0030 Run it with the -v switch instead:
0031 
0032 python M.py -v
0033 
0034 and a detailed report of all examples tried is printed to stdout, along
0035 with assorted summaries at the end.
0036 
0037 You can force verbose mode by passing "verbose=True" to testmod, or prohibit
0038 it by passing "verbose=False".  In either of those cases, sys.argv is not
0039 examined by testmod.
0040 
0041 There are a variety of other ways to run doctests, including integration
0042 with the unittest framework, and support for running non-Python text
0043 files containing doctests.  There are also many ways to override parts
0044 of doctest's default behaviors.  See the Library Reference Manual for
0045 details.
0046 """
0047 
0048 __docformat__ = 'reStructuredText en'
0049 
0050 __all__ = [
0051     # 0, Option Flags
0052     'register_optionflag',
0053     'DONT_ACCEPT_TRUE_FOR_1',
0054     'DONT_ACCEPT_BLANKLINE',
0055     'NORMALIZE_WHITESPACE',
0056     'ELLIPSIS',
0057     'IGNORE_EXCEPTION_DETAIL',
0058     'COMPARISON_FLAGS',
0059     'REPORT_UDIFF',
0060     'REPORT_CDIFF',
0061     'REPORT_NDIFF',
0062     'REPORT_ONLY_FIRST_FAILURE',
0063     'REPORTING_FLAGS',
0064     # 1. Utility Functions
0065     'is_private',
0066     # 2. Example & DocTest
0067     'Example',
0068     'DocTest',
0069     # 3. Doctest Parser
0070     'DocTestParser',
0071     # 4. Doctest Finder
0072     'DocTestFinder',
0073     # 5. Doctest Runner
0074     'DocTestRunner',
0075     'OutputChecker',
0076     'DocTestFailure',
0077     'UnexpectedException',
0078     'DebugRunner',
0079     # 6. Test Functions
0080     'testmod',
0081     'testfile',
0082     'run_docstring_examples',
0083     # 7. Tester
0084     'Tester',
0085     # 8. Unittest Support
0086     'DocTestSuite',
0087     'DocFileSuite',
0088     'set_unittest_reportflags',
0089     # 9. Debugging Support
0090     'script_from_examples',
0091     'testsource',
0092     'debug_src',
0093     'debug',
0094 ]
0095 
0096 import __future__
0097 
0098 import sys, traceback, inspect, linecache, os, re, types
0099 import unittest, difflib, pdb, tempfile
0100 import warnings
0101 from StringIO import StringIO
0102 
0103 # Don't whine about the deprecated is_private function in this
0104 # module's tests.
0105 warnings.filterwarnings("ignore", "is_private", DeprecationWarning,
0106                         __name__, 0)
0107 
0108 real_pdb_set_trace = pdb.set_trace
0109 
0110 # There are 4 basic classes:
0111 #  - Example: a <source, want> pair, plus an intra-docstring line number.
0112 #  - DocTest: a collection of examples, parsed from a docstring, plus
0113 #    info about where the docstring came from (name, filename, lineno).
0114 #  - DocTestFinder: extracts DocTests from a given object's docstring and
0115 #    its contained objects' docstrings.
0116 #  - DocTestRunner: runs DocTest cases, and accumulates statistics.
0117 #
0118 # So the basic picture is:
0119 #
0120 #                             list of:
0121 # +------+                   +---------+                   +-------+
0122 # |object| --DocTestFinder-> | DocTest | --DocTestRunner-> |results|
0123 # +------+                   +---------+                   +-------+
0124 #                            | Example |
0125 #                            |   ...   |
0126 #                            | Example |
0127 #                            +---------+
0128 
0129 # Option constants.
0130 
0131 OPTIONFLAGS_BY_NAME = {}
0132 def register_optionflag(name):
0133     flag = 1 << len(OPTIONFLAGS_BY_NAME)
0134     OPTIONFLAGS_BY_NAME[name] = flag
0135     return flag
0136 
0137 DONT_ACCEPT_TRUE_FOR_1 = register_optionflag('DONT_ACCEPT_TRUE_FOR_1')
0138 DONT_ACCEPT_BLANKLINE = register_optionflag('DONT_ACCEPT_BLANKLINE')
0139 NORMALIZE_WHITESPACE = register_optionflag('NORMALIZE_WHITESPACE')
0140 ELLIPSIS = register_optionflag('ELLIPSIS')
0141 IGNORE_EXCEPTION_DETAIL = register_optionflag('IGNORE_EXCEPTION_DETAIL')
0142 
0143 COMPARISON_FLAGS = (DONT_ACCEPT_TRUE_FOR_1 |
0144                     DONT_ACCEPT_BLANKLINE |
0145                     NORMALIZE_WHITESPACE |
0146                     ELLIPSIS |
0147                     IGNORE_EXCEPTION_DETAIL)
0148 
0149 REPORT_UDIFF = register_optionflag('REPORT_UDIFF')
0150 REPORT_CDIFF = register_optionflag('REPORT_CDIFF')
0151 REPORT_NDIFF = register_optionflag('REPORT_NDIFF')
0152 REPORT_ONLY_FIRST_FAILURE = register_optionflag('REPORT_ONLY_FIRST_FAILURE')
0153 
0154 REPORTING_FLAGS = (REPORT_UDIFF |
0155                    REPORT_CDIFF |
0156                    REPORT_NDIFF |
0157                    REPORT_ONLY_FIRST_FAILURE)
0158 
0159 # Special string markers for use in `want` strings:
0160 BLANKLINE_MARKER = '<BLANKLINE>'
0161 ELLIPSIS_MARKER = '...'
0162 
0163 ######################################################################
0164 ## Table of Contents
0165 ######################################################################
0166 #  1. Utility Functions
0167 #  2. Example & DocTest -- store test cases
0168 #  3. DocTest Parser -- extracts examples from strings
0169 #  4. DocTest Finder -- extracts test cases from objects
0170 #  5. DocTest Runner -- runs test cases
0171 #  6. Test Functions -- convenient wrappers for testing
0172 #  7. Tester Class -- for backwards compatibility
0173 #  8. Unittest Support
0174 #  9. Debugging Support
0175 # 10. Example Usage
0176 
0177 ######################################################################
0178 ## 1. Utility Functions
0179 ######################################################################
0180 
0181 def is_private(prefix, base):
0182     """prefix, base -> true iff name prefix + "." + base is "private".
0183 
0184     Prefix may be an empty string, and base does not contain a period.
0185     Prefix is ignored (although functions you write conforming to this
0186     protocol may make use of it).
0187     Return true iff base begins with an (at least one) underscore, but
0188     does not both begin and end with (at least) two underscores.
0189 
0190     >>> is_private("a.b", "my_func")
0191     False
0192     >>> is_private("____", "_my_func")
0193     True
0194     >>> is_private("someclass", "__init__")
0195     False
0196     >>> is_private("sometypo", "__init_")
0197     True
0198     >>> is_private("x.y.z", "_")
0199     True
0200     >>> is_private("_x.y.z", "__")
0201     False
0202     >>> is_private("", "")  # senseless but consistent
0203     False
0204     """
0205     warnings.warn("is_private is deprecated; it wasn't useful; "
0206                   "examine DocTestFinder.find() lists instead",
0207                   DeprecationWarning, stacklevel=2)
0208     return base[:1] == "_" and not base[:2] == "__" == base[-2:]
0209 
0210 def _extract_future_flags(globs):
0211     """
0212     Return the compiler-flags associated with the future features that
0213     have been imported into the given namespace (globs).
0214     """
0215     flags = 0
0216     for fname in __future__.all_feature_names:
0217         feature = globs.get(fname, None)
0218         if feature is getattr(__future__, fname):
0219             flags |= feature.compiler_flag
0220     return flags
0221 
0222 def _normalize_module(module, depth=2):
0223     """
0224     Return the module specified by `module`.  In particular:
0225       - If `module` is a module, then return module.
0226       - If `module` is a string, then import and return the
0227         module with that name.
0228       - If `module` is None, then return the calling module.
0229         The calling module is assumed to be the module of
0230         the stack frame at the given depth in the call stack.
0231     """
0232     if inspect.ismodule(module):
0233         return module
0234     elif isinstance(module, (str, unicode)):
0235         return __import__(module, globals(), locals(), ["*"])
0236     elif module is None:
0237         return sys.modules[sys._getframe(depth).f_globals['__name__']]
0238     else:
0239         raise TypeError("Expected a module, string, or None")
0240 
0241 def _indent(s, indent=4):
0242     """
0243     Add the given number of space characters to the beginning every
0244     non-blank line in `s`, and return the result.
0245     """
0246     # This regexp matches the start of non-blank lines:
0247     return re.sub('(?m)^(?!$)', indent*' ', s)
0248 
0249 def _exception_traceback(exc_info):
0250     """
0251     Return a string containing a traceback message for the given
0252     exc_info tuple (as returned by sys.exc_info()).
0253     """
0254     # Get a traceback message.
0255     excout = StringIO()
0256     exc_type, exc_val, exc_tb = exc_info
0257     traceback.print_exception(exc_type, exc_val, exc_tb, file=excout)
0258     return excout.getvalue()
0259 
0260 # Override some StringIO methods.
0261 class _SpoofOut(StringIO):
0262     def getvalue(self):
0263         result = StringIO.getvalue(self)
0264         # If anything at all was written, make sure there's a trailing
0265         # newline.  There's no way for the expected output to indicate
0266         # that a trailing newline is missing.
0267         if result and not result.endswith("\n"):
0268             result += "\n"
0269         # Prevent softspace from screwing up the next test case, in
0270         # case they used print with a trailing comma in an example.
0271         if hasattr(self, "softspace"):
0272             del self.softspace
0273         return result
0274 
0275     def truncate(self,   size=None):
0276         StringIO.truncate(self, size)
0277         if hasattr(self, "softspace"):
0278             del self.softspace
0279 
0280 # Worst-case linear-time ellipsis matching.
0281 def _ellipsis_match(want, got):
0282     """
0283     Essentially the only subtle case:
0284     >>> _ellipsis_match('aa...aa', 'aaa')
0285     False
0286     """
0287     if ELLIPSIS_MARKER not in want:
0288         return want == got
0289 
0290     # Find "the real" strings.
0291     ws = want.split(ELLIPSIS_MARKER)
0292     assert len(ws) >= 2
0293 
0294     # Deal with exact matches possibly needed at one or both ends.
0295     startpos, endpos = 0, len(got)
0296     w = ws[0]
0297     if w:   # starts with exact match
0298         if got.startswith(w):
0299             startpos = len(w)
0300             del ws[0]
0301         else:
0302             return False
0303     w = ws[-1]
0304     if w:   # ends with exact match
0305         if got.endswith(w):
0306             endpos -= len(w)
0307             del ws[-1]
0308         else:
0309             return False
0310 
0311     if startpos > endpos:
0312         # Exact end matches required more characters than we have, as in
0313         # _ellipsis_match('aa...aa', 'aaa')
0314         return False
0315 
0316     # For the rest, we only need to find the leftmost non-overlapping
0317     # match for each piece.  If there's no overall match that way alone,
0318     # there's no overall match period.
0319     for w in ws:
0320         # w may be '' at times, if there are consecutive ellipses, or
0321         # due to an ellipsis at the start or end of `want`.  That's OK.
0322         # Search for an empty string succeeds, and doesn't change startpos.
0323         startpos = got.find(w, startpos, endpos)
0324         if startpos < 0:
0325             return False
0326         startpos += len(w)
0327 
0328     return True
0329 
0330 def _comment_line(line):
0331     "Return a commented form of the given line"
0332     line = line.rstrip()
0333     if line:
0334         return '# '+line
0335     else:
0336         return '#'
0337 
0338 class _OutputRedirectingPdb(pdb.Pdb):
0339     """
0340     A specialized version of the python debugger that redirects stdout
0341     to a given stream when interacting with the user.  Stdout is *not*
0342     redirected when traced code is executed.
0343     """
0344     def __init__(self, out):
0345         self.__out = out
0346         pdb.Pdb.__init__(self)
0347 
0348     def trace_dispatch(self, *args):
0349         # Redirect stdout to the given stream.
0350         save_stdout = sys.stdout
0351         sys.stdout = self.__out
0352         # Call Pdb's trace dispatch method.
0353         pdb.Pdb.trace_dispatch(self, *args)
0354         # Restore stdout.
0355         sys.stdout = save_stdout
0356 
0357 # [XX] Normalize with respect to os.path.pardir?
0358 def _module_relative_path(module, path):
0359     if not inspect.ismodule(module):
0360         raise TypeError, 'Expected a module: %r' % module
0361     if path.startswith('/'):
0362         raise ValueError, 'Module-relative files may not have absolute paths'
0363 
0364     # Find the base directory for the path.
0365     if hasattr(module, '__file__'):
0366         # A normal module/package
0367         basedir = os.path.split(module.__file__)[0]
0368     elif module.__name__ == '__main__':
0369         # An interactive session.
0370         if len(sys.argv)>0 and sys.argv[0] != '':
0371             basedir = os.path.split(sys.argv[0])[0]
0372         else:
0373             basedir = os.curdir
0374     else:
0375         # A module w/o __file__ (this includes builtins)
0376         raise ValueError("Can't resolve paths relative to the module " +
0377                          module + " (it has no __file__)")
0378 
0379     # Combine the base directory and the path.
0380     return os.path.join(basedir, *(path.split('/')))
0381 
0382 ######################################################################
0383 ## 2. Example & DocTest
0384 ######################################################################
0385 ## - An "example" is a <source, want> pair, where "source" is a
0386 ##   fragment of source code, and "want" is the expected output for
0387 ##   "source."  The Example class also includes information about
0388 ##   where the example was extracted from.
0389 ##
0390 ## - A "doctest" is a collection of examples, typically extracted from
0391 ##   a string (such as an object's docstring).  The DocTest class also
0392 ##   includes information about where the string was extracted from.
0393 
0394 class Example:
0395     """
0396     A single doctest example, consisting of source code and expected
0397     output.  `Example` defines the following attributes:
0398 
0399       - source: A single Python statement, always ending with a newline.
0400         The constructor adds a newline if needed.
0401 
0402       - want: The expected output from running the source code (either
0403         from stdout, or a traceback in case of exception).  `want` ends
0404         with a newline unless it's empty, in which case it's an empty
0405         string.  The constructor adds a newline if needed.
0406 
0407       - exc_msg: The exception message generated by the example, if
0408         the example is expected to generate an exception; or `None` if
0409         it is not expected to generate an exception.  This exception
0410         message is compared against the return value of
0411         `traceback.format_exception_only()`.  `exc_msg` ends with a
0412         newline unless it's `None`.  The constructor adds a newline
0413         if needed.
0414 
0415       - lineno: The line number within the DocTest string containing
0416         this Example where the Example begins.  This line number is
0417         zero-based, with respect to the beginning of the DocTest.
0418 
0419       - indent: The example's indentation in the DocTest string.
0420         I.e., the number of space characters that preceed the
0421         example's first prompt.
0422 
0423       - options: A dictionary mapping from option flags to True or
0424         False, which is used to override default options for this
0425         example.  Any option flags not contained in this dictionary
0426         are left at their default value (as specified by the
0427         DocTestRunner's optionflags).  By default, no options are set.
0428     """
0429     def __init__(self, source, want, exc_msg=None, lineno=0, indent=0,
0430                  options=None):
0431         # Normalize inputs.
0432         if not source.endswith('\n'):
0433             source += '\n'
0434         if want and not want.endswith('\n'):
0435             want += '\n'
0436         if exc_msg is not None and not exc_msg.endswith('\n'):
0437             exc_msg += '\n'
0438         # Store properties.
0439         self.source = source
0440         self.want = want
0441         self.lineno = lineno
0442         self.indent = indent
0443         if options is None: options = {}
0444         self.options = options
0445         self.exc_msg = exc_msg
0446 
0447 class DocTest:
0448     """
0449     A collection of doctest examples that should be run in a single
0450     namespace.  Each `DocTest` defines the following attributes:
0451 
0452       - examples: the list of examples.
0453 
0454       - globs: The namespace (aka globals) that the examples should
0455         be run in.
0456 
0457       - name: A name identifying the DocTest (typically, the name of
0458         the object whose docstring this DocTest was extracted from).
0459 
0460       - filename: The name of the file that this DocTest was extracted
0461         from, or `None` if the filename is unknown.
0462 
0463       - lineno: The line number within filename where this DocTest
0464         begins, or `None` if the line number is unavailable.  This
0465         line number is zero-based, with respect to the beginning of
0466         the file.
0467 
0468       - docstring: The string that the examples were extracted from,
0469         or `None` if the string is unavailable.
0470     """
0471     def __init__(self, examples, globs, name, filename, lineno, docstring):
0472         """
0473         Create a new DocTest containing the given examples.  The
0474         DocTest's globals are initialized with a copy of `globs`.
0475         """
0476         assert not isinstance(examples, basestring), \
0477                "DocTest no longer accepts str; use DocTestParser instead"
0478         self.examples = examples
0479         self.docstring = docstring
0480         self.globs = globs.copy()
0481         self.name = name
0482         self.filename = filename
0483         self.lineno = lineno
0484 
0485     def __repr__(self):
0486         if len(self.examples) == 0:
0487             examples = 'no examples'
0488         elif len(self.examples) == 1:
0489             examples = '1 example'
0490         else:
0491             examples = '%d examples' % len(self.examples)
0492         return ('<DocTest %s from %s:%s (%s)>' %
0493                 (self.name, self.filename, self.lineno, examples))
0494 
0495 
0496     # This lets us sort tests by name:
0497     def __cmp__(self, other):
0498         if not isinstance(other, DocTest):
0499             return -1
0500         return cmp((self.name, self.filename, self.lineno, id(self)),
0501                    (other.name, other.filename, other.lineno, id(other)))
0502 
0503 ######################################################################
0504 ## 3. DocTestParser
0505 ######################################################################
0506 
0507 class DocTestParser:
0508     """
0509     A class used to parse strings containing doctest examples.
0510     """
0511     # This regular expression is used to find doctest examples in a
0512     # string.  It defines three groups: `source` is the source code
0513     # (including leading indentation and prompts); `indent` is the
0514     # indentation of the first (PS1) line of the source code; and
0515     # `want` is the expected output (including leading indentation).
0516     _EXAMPLE_RE = re.compile(r'''
0517         # Source consists of a PS1 line followed by zero or more PS2 lines.
0518         (?P<source>
0519             (?:^(?P<indent> [ ]*) >>>    .*)    # PS1 line
0520             (?:\n           [ ]*  \.\.\. .*)*)  # PS2 lines
0521         \n?
0522         # Want consists of any non-blank lines that do not start with PS1.
0523         (?P<want> (?:(?![ ]*$)    # Not a blank line
0524                      (?![ ]*>>>)  # Not a line starting with PS1
0525                      .*$\n?       # But any other line
0526                   )*)
0527         ''', re.MULTILINE | re.VERBOSE)
0528 
0529     # A regular expression for handling `want` strings that contain
0530     # expected exceptions.  It divides `want` into three pieces:
0531     #    - the traceback header line (`hdr`)
0532     #    - the traceback stack (`stack`)
0533     #    - the exception message (`msg`), as generated by
0534     #      traceback.format_exception_only()
0535     # `msg` may have multiple lines.  We assume/require that the
0536     # exception message is the first non-indented line starting with a word
0537     # character following the traceback header line.
0538     _EXCEPTION_RE = re.compile(r"""
0539         # Grab the traceback header.  Different versions of Python have
0540         # said different things on the first traceback line.
0541         ^(?P<hdr> Traceback\ \(
0542             (?: most\ recent\ call\ last
0543             |   innermost\ last
0544             ) \) :
0545         )
0546         \s* $                # toss trailing whitespace on the header.
0547         (?P<stack> .*?)      # don't blink: absorb stuff until...
0548         ^ (?P<msg> \w+ .*)   #     a line *starts* with alphanum.
0549         """, re.VERBOSE | re.MULTILINE | re.DOTALL)
0550 
0551     # A callable returning a true value iff its argument is a blank line
0552     # or contains a single comment.
0553     _IS_BLANK_OR_COMMENT = re.compile(r'^[ ]*(#.*)?$').match
0554 
0555     def parse(self, string, name='<string>'):
0556         """
0557         Divide the given string into examples and intervening text,
0558         and return them as a list of alternating Examples and strings.
0559         Line numbers for the Examples are 0-based.  The optional
0560         argument `name` is a name identifying this string, and is only
0561         used for error messages.
0562         """
0563         string = string.expandtabs()
0564         # If all lines begin with the same indentation, then strip it.
0565         min_indent = self._min_indent(string)
0566         if min_indent > 0:
0567             string = '\n'.join([l[min_indent:] for l in string.split('\n')])
0568 
0569         output = []
0570         charno, lineno = 0, 0
0571         # Find all doctest examples in the string:
0572         for m in self._EXAMPLE_RE.finditer(string):
0573             # Add the pre-example text to `output`.
0574             output.append(string[charno:m.start()])
0575             # Update lineno (lines before this example)
0576             lineno += string.count('\n', charno, m.start())
0577             # Extract info from the regexp match.
0578             (source, options, want, exc_msg) = \
0579                      self._parse_example(m, name, lineno)
0580             # Create an Example, and add it to the list.
0581             if not self._IS_BLANK_OR_COMMENT(source):
0582                 output.append( Example(source, want, exc_msg,
0583                                     lineno=lineno,
0584                                     indent=min_indent+len(m.group('indent')),
0585                                     options=options) )
0586             # Update lineno (lines inside this example)
0587             lineno += string.count('\n', m.start(), m.end())
0588             # Update charno.
0589             charno = m.end()
0590         # Add any remaining post-example text to `output`.
0591         output.append(string[charno:])
0592         return output
0593 
0594     def get_doctest(self, string, globs, name, filename, lineno):
0595         """
0596         Extract all doctest examples from the given string, and
0597         collect them into a `DocTest` object.
0598 
0599         `globs`, `name`, `filename`, and `lineno` are attributes for
0600         the new `DocTest` object.  See the documentation for `DocTest`
0601         for more information.
0602         """
0603         return DocTest(self.get_examples(string, name), globs,
0604                        name, filename, lineno, string)
0605 
0606     def get_examples(self, string, name='<string>'):
0607         """
0608         Extract all doctest examples from the given string, and return
0609         them as a list of `Example` objects.  Line numbers are
0610         0-based, because it's most common in doctests that nothing
0611         interesting appears on the same line as opening triple-quote,
0612         and so the first interesting line is called \"line 1\" then.
0613 
0614         The optional argument `name` is a name identifying this
0615         string, and is only used for error messages.
0616         """
0617         return [x for x in self.parse(string, name)
0618                 if isinstance(x, Example)]
0619 
0620     def _parse_example(self, m, name, lineno):
0621         """
0622         Given a regular expression match from `_EXAMPLE_RE` (`m`),
0623         return a pair `(source, want)`, where `source` is the matched
0624         example's source code (with prompts and indentation stripped);
0625         and `want` is the example's expected output (with indentation
0626         stripped).
0627 
0628         `name` is the string's name, and `lineno` is the line number
0629         where the example starts; both are used for error messages.
0630         """
0631         # Get the example's indentation level.
0632         indent = len(m.group('indent'))
0633 
0634         # Divide source into lines; check that they're properly
0635         # indented; and then strip their indentation & prompts.
0636         source_lines = m.group('source').split('\n')
0637         self._check_prompt_blank(source_lines, indent, name, lineno)
0638         self._check_prefix(source_lines[1:], ' '*indent + '.', name, lineno)
0639         source = '\n'.join([sl[indent+4:] for sl in source_lines])
0640 
0641         # Divide want into lines; check that it's properly indented; and
0642         # then strip the indentation.  Spaces before the last newline should
0643         # be preserved, so plain rstrip() isn't good enough.
0644         want = m.group('want')
0645         want_lines = want.split('\n')
0646         if len(want_lines) > 1 and re.match(r' *$', want_lines[-1]):
0647             del want_lines[-1]  # forget final newline & spaces after it
0648         self._check_prefix(want_lines, ' '*indent, name,
0649                            lineno + len(source_lines))
0650         want = '\n'.join([wl[indent:] for wl in want_lines])
0651 
0652         # If `want` contains a traceback message, then extract it.
0653         m = self._EXCEPTION_RE.match(want)
0654         if m:
0655             exc_msg = m.group('msg')
0656         else:
0657             exc_msg = None
0658 
0659         # Extract options from the source.
0660         options = self._find_options(source, name, lineno)
0661 
0662         return source, options, want, exc_msg
0663 
0664     # This regular expression looks for option directives in the
0665     # source code of an example.  Option directives are comments
0666     # starting with "doctest:".  Warning: this may give false
0667     # positives for string-literals that contain the string
0668     # "#doctest:".  Eliminating these false positives would require
0669     # actually parsing the string; but we limit them by ignoring any
0670     # line containing "#doctest:" that is *followed* by a quote mark.
0671     _OPTION_DIRECTIVE_RE = re.compile(r'#\s*doctest:\s*([^\n\'"]*)$',
0672                                       re.MULTILINE)
0673 
0674     def _find_options(self, source, name, lineno):
0675         """
0676         Return a dictionary containing option overrides extracted from
0677         option directives in the given source string.
0678 
0679         `name` is the string's name, and `lineno` is the line number
0680         where the example starts; both are used for error messages.
0681         """
0682         options = {}
0683         # (note: with the current regexp, this will match at most once:)
0684         for m in self._OPTION_DIRECTIVE_RE.finditer(source):
0685             option_strings = m.group(1).replace(',', ' ').split()
0686             for option in option_strings:
0687                 if (option[0] not in '+-' or
0688                     option[1:] not in OPTIONFLAGS_BY_NAME):
0689                     raise ValueError('line %r of the doctest for %s '
0690                                      'has an invalid option: %r' %
0691                                      (lineno+1, name, option))
0692                 flag = OPTIONFLAGS_BY_NAME[option[1:]]
0693                 options[flag] = (option[0] == '+')
0694         if options and self._IS_BLANK_OR_COMMENT(source):
0695             raise ValueError('line %r of the doctest for %s has an option '
0696                              'directive on a line with no example: %r' %
0697                              (lineno, name, source))
0698         return options
0699 
0700     # This regular expression finds the indentation of every non-blank
0701     # line in a string.
0702     _INDENT_RE = re.compile('^([ ]*)(?=\S)', re.MULTILINE)
0703 
0704     def _min_indent(self, s):
0705         "Return the minimum indentation of any non-blank line in `s`"
0706         indents = [len(indent) for indent in self._INDENT_RE.findall(s)]
0707         if len(indents) > 0:
0708             return min(indents)
0709         else:
0710             return 0
0711 
0712     def _check_prompt_blank(self, lines, indent, name, lineno):
0713         """
0714         Given the lines of a source string (including prompts and
0715         leading indentation), check to make sure that every prompt is
0716         followed by a space character.  If any line is not followed by
0717         a space character, then raise ValueError.
0718         """
0719         for i, line in enumerate(lines):
0720             if len(line) >= indent+4 and line[indent+3] != ' ':
0721                 raise ValueError('line %r of the docstring for %s '
0722                                  'lacks blank after %s: %r' %
0723                                  (lineno+i+1, name,
0724                                   line[indent:indent+3], line))
0725 
0726     def _check_prefix(self, lines, prefix, name, lineno):
0727         """
0728         Check that every line in the given list starts with the given
0729         prefix; if any line does not, then raise a ValueError.
0730         """
0731         for i, line in enumerate(lines):
0732             if line and not line.startswith(prefix):
0733                 raise ValueError('line %r of the docstring for %s has '
0734                                  'inconsistent leading whitespace: %r' %
0735                                  (lineno+i+1, name, line))
0736 
0737 
0738 ######################################################################
0739 ## 4. DocTest Finder
0740 ######################################################################
0741 
0742 class DocTestFinder:
0743     """
0744     A class used to extract the DocTests that are relevant to a given
0745     object, from its docstring and the docstrings of its contained
0746     objects.  Doctests can currently be extracted from the following
0747     object types: modules, functions, classes, methods, staticmethods,
0748     classmethods, and properties.
0749     """
0750 
0751     def __init__(self, verbose=False, parser=DocTestParser(),
0752                  recurse=True, _namefilter=None, exclude_empty=True):
0753         """
0754         Create a new doctest finder.
0755 
0756         The optional argument `parser` specifies a class or
0757         function that should be used to create new DocTest objects (or
0758         objects that implement the same interface as DocTest).  The
0759         signature for this factory function should match the signature
0760         of the DocTest constructor.
0761 
0762         If the optional argument `recurse` is false, then `find` will
0763         only examine the given object, and not any contained objects.
0764 
0765         If the optional argument `exclude_empty` is false, then `find`
0766         will include tests for objects with empty docstrings.
0767         """
0768         self._parser = parser
0769         self._verbose = verbose
0770         self._recurse = recurse
0771         self._exclude_empty = exclude_empty
0772         # _namefilter is undocumented, and exists only for temporary backward-
0773         # compatibility support of testmod's deprecated isprivate mess.
0774         self._namefilter = _namefilter
0775 
0776     def find(self, obj, name=None, module=None, globs=None,
0777              extraglobs=None):
0778         """
0779         Return a list of the DocTests that are defined by the given
0780         object's docstring, or by any of its contained objects'
0781         docstrings.
0782 
0783         The optional parameter `module` is the module that contains
0784         the given object.  If the module is not specified or is None, then
0785         the test finder will attempt to automatically determine the
0786         correct module.  The object's module is used:
0787 
0788             - As a default namespace, if `globs` is not specified.
0789             - To prevent the DocTestFinder from extracting DocTests
0790               from objects that are imported from other modules.
0791             - To find the name of the file containing the object.
0792             - To help find the line number of the object within its
0793               file.
0794 
0795         Contained objects whose module does not match `module` are ignored.
0796 
0797         If `module` is False, no attempt to find the module will be made.
0798         This is obscure, of use mostly in tests:  if `module` is False, or
0799         is None but cannot be found automatically, then all objects are
0800         considered to belong to the (non-existent) module, so all contained
0801         objects will (recursively) be searched for doctests.
0802 
0803         The globals for each DocTest is formed by combining `globs`
0804         and `extraglobs` (bindings in `extraglobs` override bindings
0805         in `globs`).  A new copy of the globals dictionary is created
0806         for each DocTest.  If `globs` is not specified, then it
0807         defaults to the module's `__dict__`, if specified, or {}
0808         otherwise.  If `extraglobs` is not specified, then it defaults
0809         to {}.
0810 
0811         """
0812         # If name was not specified, then extract it from the object.
0813         if name is None:
0814             name = getattr(obj, '__name__', None)
0815             if name is None:
0816                 raise ValueError("DocTestFinder.find: name must be given "
0817                         "when obj.__name__ doesn't exist: %r" %
0818                                  (type(obj),))
0819 
0820         # Find the module that contains the given object (if obj is
0821         # a module, then module=obj.).  Note: this may fail, in which
0822         # case module will be None.
0823         if module is False:
0824             module = None
0825         elif module is None:
0826             module = inspect.getmodule(obj)
0827 
0828         # Read the module's source code.  This is used by
0829         # DocTestFinder._find_lineno to find the line number for a
0830         # given object's docstring.
0831         try:
0832             file = inspect.getsourcefile(obj) or inspect.getfile(obj)
0833             source_lines = linecache.getlines(file)
0834             if not source_lines:
0835                 source_lines = None
0836         except TypeError:
0837             source_lines = None
0838 
0839         # Initialize globals, and merge in extraglobs.
0840         if globs is None:
0841             if module is None:
0842                 globs = {}
0843             else:
0844                 globs = module.__dict__.copy()
0845         else:
0846             globs = globs.copy()
0847         if extraglobs is not None:
0848             globs.update(extraglobs)
0849 
0850         # Recursively expore `obj`, extracting DocTests.
0851         tests = []
0852         self._find(tests, obj, name, module, source_lines, globs, {})
0853         return tests
0854 
0855     def _filter(self, obj, prefix, base):
0856         """
0857         Return true if the given object should not be examined.
0858         """
0859         return (self._namefilter is not None and
0860                 self._namefilter(prefix, base))
0861 
0862     def _from_module(self, module, object):
0863         """
0864         Return true if the given object is defined in the given
0865         module.
0866         """
0867         if module is None:
0868             return True
0869         elif inspect.isfunction(object):
0870             return module.__dict__ is object.func_globals
0871         elif inspect.isclass(object):
0872             return module.__name__ == object.__module__
0873         elif inspect.getmodule(object) is not None:
0874             return module is inspect.getmodule(object)
0875         elif hasattr(object, '__module__'):
0876             return module.__name__ == object.__module__
0877         elif isinstance(object, property):
0878             return True # [XX] no way not be sure.
0879         else:
0880             raise ValueError("object must be a class or function")
0881 
0882     def _find(self, tests, obj, name, module, source_lines, globs, seen):
0883         """
0884         Find tests for the given object and any contained objects, and
0885         add them to `tests`.
0886         """
0887         if self._verbose:
0888             print 'Finding tests in %s' % name
0889 
0890         # If we've already processed this object, then ignore it.
0891         if id(obj) in seen:
0892             return
0893         seen[id(obj)] = 1
0894 
0895         # Find a test for this object, and add it to the list of tests.
0896         test = self._get_test(obj, name, module, globs, source_lines)
0897         if test is not None:
0898             tests.append(test)
0899 
0900         # Look for tests in a module's contained objects.
0901         if inspect.ismodule(obj) and self._recurse:
0902             for valname, val in obj.__dict__.items():
0903                 # Check if this contained object should be ignored.
0904                 if self._filter(val, name, valname):
0905                     continue
0906                 valname = '%s.%s' % (name, valname)
0907                 # Recurse to functions & classes.
0908                 if ((inspect.isfunction(val) or inspect.isclass(val)) and
0909                     self._from_module(module, val)):
0910                     self._find(tests, val, valname, module, source_lines,
0911                                globs, seen)
0912 
0913         # Look for tests in a module's __test__ dictionary.
0914         if inspect.ismodule(obj) and self._recurse:
0915             for valname, val in getattr(obj, '__test__', {}).items():
0916                 if not isinstance(valname, basestring):
0917                     raise ValueError("DocTestFinder.find: __test__ keys "
0918                                      "must be strings: %r" %
0919                                      (type(valname),))
0920                 if not (inspect.isfunction(val) or inspect.isclass(val) or
0921                         inspect.ismethod(val) or inspect.ismodule(val) or
0922                         isinstance(val, basestring)):
0923                     raise ValueError("DocTestFinder.find: __test__ values "
0924                                      "must be strings, functions, methods, "
0925                                      "classes, or modules: %r" %
0926                                      (type(val),))
0927                 valname = '%s.__test__.%s' % (name, valname)
0928                 self._find(tests, val, valname, module, source_lines,
0929                            globs, seen)
0930 
0931         # Look for tests in a class's contained objects.
0932         if inspect.isclass(obj) and self._recurse:
0933             for valname, val in obj.__dict__.items():
0934                 # Check if this contained object should be ignored.
0935                 if self._filter(val, name, valname):
0936                     continue
0937                 # Special handling for staticmethod/classmethod.
0938                 if isinstance(val, staticmethod):
0939                     val = getattr(obj, valname)
0940                 if isinstance(val, classmethod):
0941                     val = getattr(obj, valname).im_func
0942 
0943                 # Recurse to methods, properties, and nested classes.
0944                 if ((inspect.isfunction(val) or inspect.isclass(val) or
0945                       isinstance(val, property)) and
0946                       self._from_module(module, val)):
0947                     valname = '%s.%s' % (name, valname)
0948                     self._find(tests, val, valname, module, source_lines,
0949                                globs, seen)
0950 
0951     def _get_test(self, obj, name, module, globs, source_lines):
0952         """
0953         Return a DocTest for the given object, if it defines a docstring;
0954         otherwise, return None.
0955         """
0956         # Extract the object's docstring.  If it doesn't have one,
0957         # then return None (no test for this object).
0958         if isinstance(obj, basestring):
0959             docstring = obj
0960         else:
0961             try:
0962                 if obj.__doc__ is None:
0963                     docstring = ''
0964                 else:
0965                     docstring = obj.__doc__
0966                     if not isinstance(docstring, basestring):
0967                         docstring = str(docstring)
0968             except (TypeError, AttributeError):
0969                 docstring = ''
0970 
0971         # Find the docstring's location in the file.
0972         lineno = self._find_lineno(obj, source_lines)
0973 
0974         # Don't bother if the docstring is empty.
0975         if self._exclude_empty and not docstring:
0976             return None
0977 
0978         # Return a DocTest for this object.
0979         if module is None:
0980             filename = None
0981         else:
0982             filename = getattr(module, '__file__', module.__name__)
0983             if filename[-4:] in (".pyc", ".pyo"):
0984                 filename = filename[:-1]
0985         return self._parser.get_doctest(docstring, globs, name,
0986                                         filename, lineno)
0987 
0988     def _find_lineno(self, obj, source_lines):
0989         """
0990         Return a line number of the given object's docstring.  Note:
0991         this method assumes that the object has a docstring.
0992         """
0993         lineno = None
0994 
0995         # Find the line number for modules.
0996         if inspect.ismodule(obj):
0997             lineno = 0
0998 
0999         # Find the line number for classes.
1000         # Note: this could be fooled if a class is defined multiple
1001         # times in a single file.
1002         if inspect.isclass(obj):
1003             if source_lines is None:
1004                 return None
1005             pat = re.compile(r'^\s*class\s*%s\b' %
1006                              getattr(obj, '__name__', '-'))
1007             for i, line in enumerate(source_lines):
1008                 if pat.match(line):
1009                     lineno = i
1010                     break
1011 
1012         # Find the line number for functions & methods.
1013         if inspect.ismethod(obj): obj = obj.im_func
1014         if inspect.isfunction(obj): obj = obj.func_code
1015         if inspect.istraceback(obj): obj = obj.tb_frame
1016         if inspect.isframe(obj): obj = obj.f_code
1017         if inspect.iscode(obj):
1018             lineno = getattr(obj, 'co_firstlineno', None)-1
1019 
1020         # Find the line number where the docstring starts.  Assume
1021         # that it's the first line that begins with a quote mark.
1022         # Note: this could be fooled by a multiline function
1023         # signature, where a continuation line begins with a quote
1024         # mark.
1025         if lineno is not None:
1026             if source_lines is None:
1027                 return lineno+1
1028             pat = re.compile('(^|.*:)\s*\w*("|\')')
1029             for lineno in range(lineno, len(source_lines)):
1030                 if pat.match(source_lines[lineno]):
1031                     return lineno
1032 
1033         # We couldn't find the line number.
1034         return None
1035 
1036 ######################################################################
1037 ## 5. DocTest Runner
1038 ######################################################################
1039 
1040 class DocTestRunner:
1041     """
1042     A class used to run DocTest test cases, and accumulate statistics.
1043     The `run` method is used to process a single DocTest case.  It
1044     returns a tuple `(f, t)`, where `t` is the number of test cases
1045     tried, and `f` is the number of test cases that failed.
1046 
1047         >>> tests = DocTestFinder().find(_TestClass)
1048         >>> runner = DocTestRunner(verbose=False)
1049         >>> for test in tests:
1050         ...     print runner.run(test)
1051         (0, 2)
1052         (0, 1)
1053         (0, 2)
1054         (0, 2)
1055 
1056     The `summarize` method prints a summary of all the test cases that
1057     have been run by the runner, and returns an aggregated `(f, t)`
1058     tuple:
1059 
1060         >>> runner.summarize(verbose=1)
1061         4 items passed all tests:
1062            2 tests in _TestClass
1063            2 tests in _TestClass.__init__
1064            2 tests in _TestClass.get
1065            1 tests in _TestClass.square
1066         7 tests in 4 items.
1067         7 passed and 0 failed.
1068         Test passed.
1069         (0, 7)
1070 
1071     The aggregated number of tried examples and failed examples is
1072     also available via the `tries` and `failures` attributes:
1073 
1074         >>> runner.tries
1075         7
1076         >>> runner.failures
1077         0
1078 
1079     The comparison between expected outputs and actual outputs is done
1080     by an `OutputChecker`.  This comparison may be customized with a
1081     number of option flags; see the documentation for `testmod` for
1082     more information.  If the option flags are insufficient, then the
1083     comparison may also be customized by passing a subclass of
1084     `OutputChecker` to the constructor.
1085 
1086     The test runner's display output can be controlled in two ways.
1087     First, an output function (`out) can be passed to
1088     `TestRunner.run`; this function will be called with strings that
1089     should be displayed.  It defaults to `sys.stdout.write`.  If
1090     capturing the output is not sufficient, then the display output
1091     can be also customized by subclassing DocTestRunner, and
1092     overriding the methods `report_start`, `report_success`,
1093     `report_unexpected_exception`, and `report_failure`.
1094     """
1095     # This divider string is used to separate failure messages, and to
1096     # separate sections of the summary.
1097     DIVIDER = "*" * 70
1098 
1099     def __init__(self, checker=None, verbose=None, optionflags=0):
1100         """
1101         Create a new test runner.
1102 
1103         Optional keyword arg `checker` is the `OutputChecker` that
1104         should be used to compare the expected outputs and actual
1105         outputs of doctest examples.
1106 
1107         Optional keyword arg 'verbose' prints lots of stuff if true,
1108         only failures if false; by default, it's true iff '-v' is in
1109         sys.argv.
1110 
1111         Optional argument `optionflags` can be used to control how the
1112         test runner compares expected output to actual output, and how
1113         it displays failures.  See the documentation for `testmod` for
1114         more information.
1115         """
1116         self._checker = checker or OutputChecker()
1117         if verbose is None:
1118             verbose = '-v' in sys.argv
1119         self._verbose = verbose
1120         self.optionflags = optionflags
1121         self.original_optionflags = optionflags
1122 
1123         # Keep track of the examples we've run.
1124         self.tries = 0
1125         self.failures = 0
1126         self._name2ft = {}
1127 
1128         # Create a fake output target for capturing doctest output.
1129         self._fakeout = _SpoofOut()
1130 
1131     #/////////////////////////////////////////////////////////////////
1132     # Reporting methods
1133     #/////////////////////////////////////////////////////////////////
1134 
1135     def report_start(self, out, test, example):
1136         """
1137         Report that the test runner is about to process the given
1138         example.  (Only displays a message if verbose=True)
1139         """
1140         if self._verbose:
1141             if example.want:
1142                 out('Trying:\n' + _indent(example.source) +
1143                     'Expecting:\n' + _indent(example.want))
1144             else:
1145                 out('Trying:\n' + _indent(example.source) +
1146                     'Expecting nothing\n')
1147 
1148     def report_success(self, out, test, example, got):
1149         """
1150         Report that the given example ran successfully.  (Only
1151         displays a message if verbose=True)
1152         """
1153         if self._verbose:
1154             out("ok\n")
1155 
1156     def report_failure(self, out, test, example, got):
1157         """
1158         Report that the given example failed.
1159         """
1160         out(self._failure_header(test, example) +
1161             self._checker.output_difference(example, got, self.optionflags))
1162 
1163     def report_unexpected_exception(self, out, test, example, exc_info):
1164         """
1165         Report that the given example raised an unexpected exception.
1166         """
1167         out(self._failure_header(test, example) +
1168             'Exception raised:\n' + _indent(_exception_traceback(exc_info)))
1169 
1170     def _failure_header(self, test, example):
1171         out = [self.DIVIDER]
1172         if test.filename:
1173             if test.lineno is not None and example.lineno is not None:
1174                 lineno = test.lineno + example.lineno + 1
1175             else:
1176                 lineno = '?'
1177             out.append('File "%s", line %s, in %s' %
1178                        (test.filename, lineno, test.name))
1179         else:
1180             out.append('Line %s, in %s' % (example.lineno+1, test.name))
1181         out.append('Failed example:')
1182         source = example.source
1183         out.append(_indent(source))
1184         return '\n'.join(out)
1185 
1186     #/////////////////////////////////////////////////////////////////
1187     # DocTest Running
1188     #/////////////////////////////////////////////////////////////////
1189 
1190     def __run(self, test, compileflags, out):
1191         """
1192         Run the examples in `test`.  Write the outcome of each example
1193         with one of the `DocTestRunner.report_*` methods, using the
1194         writer function `out`.  `compileflags` is the set of compiler
1195         flags that should be used to execute examples.  Return a tuple
1196         `(f, t)`, where `t` is the number of examples tried, and `f`
1197         is the number of examples that failed.  The examples are run
1198         in the namespace `test.globs`.
1199         """
1200         # Keep track of the number of failures and tries.
1201         failures = tries = 0
1202 
1203         # Save the option flags (since option directives can be used
1204         # to modify them).
1205         original_optionflags = self.optionflags
1206 
1207         SUCCESS, FAILURE, BOOM = range(3) # `outcome` state
1208 
1209         check = self._checker.check_output
1210 
1211         # Process each example.
1212         for examplenum, example in enumerate(test.examples):
1213 
1214             # If REPORT_ONLY_FIRST_FAILURE is set, then supress
1215             # reporting after the first failure.
1216             quiet = (self.optionflags & REPORT_ONLY_FIRST_FAILURE and
1217                      failures > 0)
1218 
1219             # Merge in the example's options.
1220             self.optionflags = original_optionflags
1221             if example.options:
1222                 for (optionflag, val) in example.options.items():
1223                     if val:
1224                         self.optionflags |= optionflag
1225                     else:
1226                         self.optionflags &= ~optionflag
1227 
1228             # Record that we started this example.
1229             tries += 1
1230             if not quiet:
1231                 self.report_start(out, test, example)
1232 
1233             # Use a special filename for compile(), so we can retrieve
1234             # the source code during interactive debugging (see
1235             # __patched_linecache_getlines).
1236             filename = '<doctest %s[%d]>' % (test.name, examplenum)
1237 
1238             # Run the example in the given context (globs), and record
1239             # any exception that gets raised.  (But don't intercept
1240             # keyboard interrupts.)
1241             try:
1242                 # Don't blink!  This is where the user's code gets run.
1243                 exec compile(example.source, filename, "single",
1244                              compileflags, 1) in test.globs
1245                 self.debugger.set_continue() # ==== Example Finished ====
1246                 exception = None
1247             except KeyboardInterrupt:
1248                 raise
1249             except:
1250                 exception = sys.exc_info()
1251                 self.debugger.set_continue() # ==== Example Finished ====
1252 
1253             got = self._fakeout.getvalue()  # the actual output
1254             self._fakeout.truncate(0)
1255             outcome = FAILURE   # guilty until proved innocent or insane
1256 
1257             # If the example executed without raising any exceptions,
1258             # verify its output.
1259             if exception is None:
1260                 if check(example.want, got, self.optionflags):
1261                     outcome = SUCCESS
1262 
1263             # The example raised an exception:  check if it was expected.
1264             else:
1265                 exc_info = sys.exc_info()
1266                 exc_msg = traceback.format_exception_only(*exc_info[:2])[-1]
1267                 if not quiet:
1268                     got += _exception_traceback(exc_info)
1269 
1270                 # If `example.exc_msg` is None, then we weren't expecting
1271                 # an exception.
1272                 if example.exc_msg is None:
1273                     outcome = BOOM
1274 
1275                 # We expected an exception:  see whether it matches.
1276                 elif check(example.exc_msg, exc_msg, self.optionflags):
1277                     outcome = SUCCESS
1278 
1279                 # Another chance if they didn't care about the detail.
1280                 elif self.optionflags & IGNORE_EXCEPTION_DETAIL:
1281                     m1 = re.match(r'[^:]*:', example.exc_msg)
1282                     m2 = re.match(r'[^:]*:', exc_msg)
1283                     if m1 and m2 and check(m1.group(0), m2.group(0),
1284                                            self.optionflags):
1285                         outcome = SUCCESS
1286 
1287             # Report the outcome.
1288             if outcome is SUCCESS:
1289                 if not quiet:
1290                     self.report_success(out, test, example, got)
1291             elif outcome is FAILURE:
1292                 if not quiet:
1293                     self.report_failure(out, test, example, got)
1294                 failures += 1
1295             elif outcome is BOOM:
1296                 if not quiet:
1297                     self.report_unexpected_exception(out, test, example,
1298                                                      exc_info)
1299                 failures += 1
1300             else:
1301                 assert False, ("unknown outcome", outcome)
1302 
1303         # Restore the option flags (in case they were modified)
1304         self.optionflags = original_optionflags
1305 
1306         # Record and return the number of failures and tries.
1307         self.__record_outcome(test, failures, tries)
1308         return failures, tries
1309 
1310     def __record_outcome(self, test, f, t):
1311         """
1312         Record the fact that the given DocTest (`test`) generated `f`
1313         failures out of `t` tried examples.
1314         """
1315         f2, t2 = self._name2ft.get(test.name, (0,0))
1316         self._name2ft[test.name] = (f+f2, t+t2)
1317         self.failures += f
1318         self.tries += t
1319 
1320     __LINECACHE_FILENAME_RE = re.compile(r'<doctest '
1321                                          r'(?P<name>[\w\.]+)'
1322                                          r'\[(?P<examplenum>\d+)\]>$')
1323     def __patched_linecache_getlines(self, filename):
1324         m = self.__LINECACHE_FILENAME_RE.match(filename)
1325         if m and m.group('name') == self.test.name:
1326             example = self.test.examples[int(m.group('examplenum'))]
1327             return example.source.splitlines(True)
1328         else:
1329             return self.save_linecache_getlines(filename)
1330 
1331     def run(self, test, compileflags=None, out=None, clear_globs=True):
1332         """
1333         Run the examples in `test`, and display the results using the
1334         writer function `out`.
1335 
1336         The examples are run in the namespace `test.globs`.  If
1337         `clear_globs` is true (the default), then this namespace will
1338         be cleared after the test runs, to help with garbage
1339         collection.  If you would like to examine the namespace after
1340         the test completes, then use `clear_globs=False`.
1341 
1342         `compileflags` gives the set of flags that should be used by
1343         the Python compiler when running the examples.  If not
1344         specified, then it will default to the set of future-import
1345         flags that apply to `globs`.
1346 
1347         The output of each example is checked using
1348         `DocTestRunner.check_output`, and the results are formatted by
1349         the `DocTestRunner.report_*` methods.
1350         """
1351         self.test = test
1352 
1353         if compileflags is None:
1354             compileflags = _extract_future_flags(test.globs)
1355 
1356         save_stdout = sys.stdout
1357         if out is None:
1358             out = save_stdout.write
1359         sys.stdout = self._fakeout
1360 
1361         # Patch pdb.set_trace to restore sys.stdout during interactive
1362         # debugging (so it's not still redirected to self._fakeout).
1363         # Note that the interactive output will go to *our*
1364         # save_stdout, even if that's not the real sys.stdout; this
1365         # allows us to write test cases for the set_trace behavior.
1366         save_set_trace = pdb.set_trace
1367         self.debugger = _OutputRedirectingPdb(save_stdout)
1368         self.debugger.reset()
1369         pdb.set_trace = self.debugger.set_trace
1370 
1371         # Patch linecache.getlines, so we can see the example's source
1372         # when we're inside the debugger.
1373         self.save_linecache_getlines = linecache.getlines
1374         linecache.getlines = self.__patched_linecache_getlines
1375 
1376         try:
1377             return self.__run(test, compileflags, out)
1378         finally:
1379             sys.stdout = save_stdout
1380             pdb.set_trace = save_set_trace
1381             linecache.getlines = self.save_linecache_getlines
1382             if clear_globs:
1383                 test.globs.clear()
1384 
1385     #/////////////////////////////////////////////////////////////////
1386     # Summarization
1387     #/////////////////////////////////////////////////////////////////
1388     def summarize(self, verbose=None):
1389         """
1390         Print a summary of all the test cases that have been run by
1391         this DocTestRunner, and return a tuple `(f, t)`, where `f` is
1392         the total number of failed examples, and `t` is the total
1393         number of tried examples.
1394 
1395         The optional `verbose` argument controls how detailed the
1396         summary is.  If the verbosity is not specified, then the
1397         DocTestRunner's verbosity is used.
1398         """
1399         if verbose is None:
1400             verbose = self._verbose
1401         notests = []
1402         passed = []
1403         failed = []
1404         totalt = totalf = 0
1405         for x in self._name2ft.items():
1406             name, (f, t) = x
1407             assert f <= t
1408             totalt += t
1409             totalf += f
1410             if t == 0:
1411                 notests.append(name)
1412             elif f == 0:
1413                 passed.append( (name, t) )
1414             else:
1415                 failed.append(x)
1416         if verbose:
1417             if notests:
1418                 print len(notests), "items had no tests:"
1419                 notests.sort()
1420                 for thing in notests:
1421                     print "   ", thing
1422             if passed:
1423                 print len(passed), "items passed all tests:"
1424                 passed.sort()
1425                 for thing, count in passed:
1426                     print " %3d tests in %s" % (count, thing)
1427         if failed:
1428             print self.DIVIDER
1429             print len(failed), "items had failures:"
1430             failed.sort()
1431             for thing, (f, t) in failed:
1432                 print " %3d of %3d in %s" % (f, t, thing)
1433         if verbose:
1434             print totalt, "tests in", len(self._name2ft), "items."
1435             print totalt - totalf, "passed and", totalf, "failed."
1436         if totalf:
1437             print "***Test Failed***", totalf, "failures."
1438         elif verbose:
1439             print "Test passed."
1440         return totalf, totalt
1441 
1442     #/////////////////////////////////////////////////////////////////
1443     # Backward compatibility cruft to maintain doctest.master.
1444     #/////////////////////////////////////////////////////////////////
1445     def merge(self, other):
1446         d = self._name2ft
1447         for name, (f, t) in other._name2ft.items():
1448             if name in d:
1449                 print "*** DocTestRunner.merge: '" + name + "' in both" \
1450                     " testers; summing outcomes."
1451                 f2, t2 = d[name]
1452                 f = f + f2
1453                 t = t + t2
1454             d[name] = f, t
1455 
1456 class OutputChecker:
1457     """
1458     A class used to check the whether the actual output from a doctest
1459     example matches the expected output.  `OutputChecker` defines two
1460     methods: `check_output`, which compares a given pair of outputs,
1461     and returns true if they match; and `output_difference`, which
1462     returns a string describing the differences between two outputs.
1463     """
1464     def check_output(self, want, got, optionflags):
1465         """
1466         Return True iff the actual output from an example (`got`)
1467         matches the expected output (`want`).  These strings are
1468         always considered to match if they are identical; but
1469         depending on what option flags the test runner is using,
1470         several non-exact match types are also possible.  See the
1471         documentation for `TestRunner` for more information about
1472         option flags.
1473         """
1474         # Handle the common case first, for efficiency:
1475         # if they're string-identical, always return true.
1476         if got == want:
1477             return True
1478 
1479         # The values True and False replaced 1 and 0 as the return
1480         # value for boolean comparisons in Python 2.3.
1481         if not (optionflags & DONT_ACCEPT_TRUE_FOR_1):
1482             if (got,want) == ("True\n", "1\n"):
1483                 return True
1484             if (got,want) == ("False\n", "0\n"):
1485                 return True
1486 
1487         # <BLANKLINE> can be used as a special sequence to signify a
1488         # blank line, unless the DONT_ACCEPT_BLANKLINE flag is used.
1489         if not (optionflags & DONT_ACCEPT_BLANKLINE):
1490             # Replace <BLANKLINE> in want with a blank line.
1491             want = re.sub('(?m)^%s\s*?$' % re.escape(BLANKLINE_MARKER),
1492                           '', want)
1493             # If a line in got contains only spaces, then remove the
1494             # spaces.
1495             got = re.sub('(?m)^\s*?$', '', got)
1496             if got == want:
1497                 return True
1498 
1499         # This flag causes doctest to ignore any differences in the
1500         # contents of whitespace strings.  Note that this can be used
1501         # in conjunction with the ELLIPSIS flag.
1502         if optionflags & NORMALIZE_WHITESPACE:
1503             got = ' '.join(got.split())
1504             want = ' '.join(want.split())
1505             if got == want:
1506                 return True
1507 
1508         # The ELLIPSIS flag says to let the sequence "..." in `want`
1509         # match any substring in `got`.
1510         if optionflags & ELLIPSIS:
1511             if _ellipsis_match(want, got):
1512                 return True
1513 
1514         # We didn't find any match; return false.
1515         return False
1516 
1517     # Should we do a fancy diff?
1518     def _do_a_fancy_diff(self, want, got, optionflags):
1519         # Not unless they asked for a fancy diff.
1520         if not optionflags & (REPORT_UDIFF |
1521                               REPORT_CDIFF |
1522                               REPORT_NDIFF):
1523             return False
1524 
1525         # If expected output uses ellipsis, a meaningful fancy diff is
1526         # too hard ... or maybe not.  In two real-life failures Tim saw,
1527         # a diff was a major help anyway, so this is commented out.
1528         # [todo] _ellipsis_match() knows which pieces do and don't match,
1529         # and could be the basis for a kick-ass diff in this case.
1530         ##if optionflags & ELLIPSIS and ELLIPSIS_MARKER in want:
1531         ##    return False
1532 
1533         # ndiff does intraline difference marking, so can be useful even
1534         # for 1-line differences.
1535         if optionflags & REPORT_NDIFF:
1536             return True
1537 
1538         # The other diff types need at least a few lines to be helpful.
1539         return want.count('\n') > 2 and got.count('\n') > 2
1540 
1541     def output_difference(self, example, got, optionflags):
1542         """
1543         Return a string describing the differences between the
1544         expected output for a given example (`example`) and the actual
1545         output (`got`).  `optionflags` is the set of option flags used
1546         to compare `want` and `got`.
1547         """
1548         want = example.want
1549         # If <BLANKLINE>s are being used, then replace blank lines
1550         # with <BLANKLINE> in the actual output string.
1551         if not (optionflags & DONT_ACCEPT_BLANKLINE):
1552             got = re.sub('(?m)^[ ]*(?=\n)', BLANKLINE_MARKER, got)
1553 
1554         # Check if we should use diff.
1555         if self._do_a_fancy_diff(want, got, optionflags):
1556             # Split want & got into lines.
1557             want_lines = want.splitlines(True)  # True == keep line ends
1558             got_lines = got.splitlines(True)
1559             # Use difflib to find their differences.
1560             if optionflags & REPORT_UDIFF:
1561                 diff = difflib.unified_diff(want_lines, got_lines, n=2)
1562                 diff = list(diff)[2:] # strip the diff header
1563                 kind = 'unified diff with -expected +actual'
1564             elif optionflags & REPORT_CDIFF:
1565                 diff = difflib.context_diff(want_lines, got_lines, n=2)
1566                 diff = list(diff)[2:] # strip the diff header
1567                 kind = 'context diff with expected followed by actual'
1568             elif optionflags & REPORT_NDIFF:
1569                 engine = difflib.Differ(charjunk=difflib.IS_CHARACTER_JUNK)
1570                 diff = list(engine.compare(want_lines, got_lines))
1571                 kind = 'ndiff with -expected +actual'
1572             else:
1573                 assert 0, 'Bad diff option'
1574             # Remove trailing whitespace on diff output.
1575             diff = [line.rstrip() + '\n' for line in diff]
1576             return 'Differences (%s):\n' % kind + _indent(''.join(diff))
1577 
1578         # If we're not using diff, then simply list the expected
1579         # output followed by the actual output.
1580         if want and got:
1581             return 'Expected:\n%sGot:\n%s' % (_indent(want), _indent(got))
1582         elif want:
1583             return 'Expected:\n%sGot nothing\n' % _indent(want)
1584         elif got:
1585             return 'Expected nothing\nGot:\n%s' % _indent(got)
1586         else:
1587             return 'Expected nothing\nGot nothing\n'
1588 
1589 class DocTestFailure(Exception):
1590     """A DocTest example has failed in debugging mode.
1591 
1592     The exception instance has variables:
1593 
1594     - test: the DocTest object being run
1595 
1596     - excample: the Example object that failed
1597 
1598     - got: the actual output
1599     """
1600     def __init__(self, test, example, got):
1601         self.test = test
1602         self.example = example
1603         self.got = got
1604 
1605     def __str__(self):
1606         return str(self.test)
1607 
1608 class UnexpectedException(Exception):
1609     """A DocTest example has encountered an unexpected exception
1610 
1611     The exception instance has variables:
1612 
1613     - test: the DocTest object being run
1614 
1615     - excample: the Example object that failed
1616 
1617     - exc_info: the exception info
1618     """
1619     def __init__(self, test, example, exc_info):
1620         self.test = test
1621         self.example = example
1622         self.exc_info = exc_info
1623 
1624     def __str__(self):
1625         return str(self.test)
1626 
1627 class DebugRunner(DocTestRunner):
1628     r"""Run doc tests but raise an exception as soon as there is a failure.
1629 
1630        If an unexpected exception occurs, an UnexpectedException is raised.
1631        It contains the test, the example, and the original exception:
1632 
1633          >>> runner = DebugRunner(verbose=False)
1634          >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
1635          ...                                    {}, 'foo', 'foo.py', 0)
1636          >>> try:
1637          ...     runner.run(test)
1638          ... except UnexpectedException, failure:
1639          ...     pass
1640 
1641          >>> failure.test is test
1642          True
1643 
1644          >>> failure.example.want
1645          '42\n'
1646 
1647          >>> exc_info = failure.exc_info
1648          >>> raise exc_info[0], exc_info[1], exc_info[2]
1649          Traceback (most recent call last):
1650          ...
1651          KeyError
1652 
1653        We wrap the original exception to give the calling application
1654        access to the test and example information.
1655 
1656        If the output doesn't match, then a DocTestFailure is raised:
1657 
1658          >>> test = DocTestParser().get_doctest('''
1659          ...      >>> x = 1
1660          ...      >>> x
1661          ...      2
1662          ...      ''', {}, 'foo', 'foo.py', 0)
1663 
1664          >>> try:
1665          ...    runner.run(test)
1666          ... except DocTestFailure, failure:
1667          ...    pass
1668 
1669        DocTestFailure objects provide access to the test:
1670 
1671          >>> failure.test is test
1672          True
1673 
1674        As well as to the example:
1675 
1676          >>> failure.example.want
1677          '2\n'
1678 
1679        and the actual output:
1680 
1681          >>> failure.got
1682          '1\n'
1683 
1684        If a failure or error occurs, the globals are left intact:
1685 
1686          >>> del test.globs['__builtins__']
1687          >>> test.globs
1688          {'x': 1}
1689 
1690          >>> test = DocTestParser().get_doctest('''
1691          ...      >>> x = 2
1692          ...      >>> raise KeyError
1693          ...      ''', {}, 'foo', 'foo.py', 0)
1694 
1695          >>> runner.run(test)
1696          Traceback (most recent call last):
1697          ...
1698          UnexpectedException: <DocTest foo from foo.py:0 (2 examples)>
1699 
1700          >>> del test.globs['__builtins__']
1701          >>> test.globs
1702          {'x': 2}
1703 
1704        But the globals are cleared if there is no error:
1705 
1706          >>> test = DocTestParser().get_doctest('''
1707          ...      >>> x = 2
1708          ...      ''', {}, 'foo', 'foo.py', 0)
1709 
1710          >>> runner.run(test)
1711          (0, 1)
1712 
1713          >>> test.globs
1714          {}
1715 
1716        """
1717 
1718     def run(self, test, compileflags=None, out=None, clear_globs=True):
1719         r = DocTestRunner.run(self, test, compileflags, out, False)
1720         if clear_globs:
1721             test.globs.clear()
1722         return r
1723 
1724     def report_unexpected_exception(self, out, test, example, exc_info):
1725         raise UnexpectedException(test, example, exc_info)
1726 
1727     def report_failure(self, out, test, example, got):
1728         raise DocTestFailure(test, example, got)
1729 
1730 ######################################################################
1731 ## 6. Test Functions
1732 ######################################################################
1733 # These should be backwards compatible.
1734 
1735 # For backward compatibility, a global instance of a DocTestRunner
1736 # class, updated by testmod.
1737 master = None
1738 
1739 def testmod(m=None, name=None, globs=None, verbose=None, isprivate=None,
1740             report=True, optionflags=0, extraglobs=None,
1741             raise_on_error=False, exclude_empty=False):
1742     """m=None, name=None, globs=None, verbose=None, isprivate=None,
1743        report=True, optionflags=0, extraglobs=None, raise_on_error=False,
1744        exclude_empty=False
1745 
1746     Test examples in docstrings in functions and classes reachable
1747     from module m (or the current module if m is not supplied), starting
1748     with m.__doc__.  Unless isprivate is specified, private names
1749     are not skipped.
1750 
1751     Also test examples reachable from dict m.__test__ if it exists and is
1752     not None.  m.__test__ maps names to functions, classes and strings;
1753     function and class docstrings are tested even if the name is private;
1754     strings are tested directly, as if they were docstrings.
1755 
1756     Return (#failures, #tests).
1757 
1758     See doctest.__doc__ for an overview.
1759 
1760     Optional keyword arg "name" gives the name of the module; by default
1761     use m.__name__.
1762 
1763     Optional keyword arg "globs" gives a dict to be used as the globals
1764     when executing examples; by default, use m.__dict__.  A copy of this
1765     dict is actually used for each docstring, so that each docstring's
1766     examples start with a clean slate.
1767 
1768     Optional keyword arg "extraglobs" gives a dictionary that should be
1769     merged into the globals that are used to execute examples.  By
1770     default, no extra globals are used.  This is new in 2.4.
1771 
1772     Optional keyword arg "verbose" prints lots of stuff if true, prints
1773     only failures if false; by default, it's true iff "-v" is in sys.argv.
1774 
1775     Optional keyword arg "report" prints a summary at the end when true,
1776     else prints nothing at the end.  In verbose mode, the summary is
1777     detailed, else very brief (in fact, empty if all tests passed).
1778 
1779     Optional keyword arg "optionflags" or's together module constants,
1780     and defaults to 0.  This is new in 2.3.  Possible values (see the
1781     docs for details):
1782 
1783         DONT_ACCEPT_TRUE_FOR_1
1784         DONT_ACCEPT_BLANKLINE
1785         NORMALIZE_WHITESPACE
1786         ELLIPSIS
1787         IGNORE_EXCEPTION_DETAIL
1788         REPORT_UDIFF
1789         REPORT_CDIFF
1790         REPORT_NDIFF
1791         REPORT_ONLY_FIRST_FAILURE
1792 
1793     Optional keyword arg "raise_on_error" raises an exception on the
1794     first unexpected exception or failure. This allows failures to be
1795     post-mortem debugged.
1796 
1797     Deprecated in Python 2.4:
1798     Optional keyword arg "isprivate" specifies a function used to
1799     determine whether a name is private.  The default function is
1800     treat all functions as public.  Optionally, "isprivate" can be
1801     set to doctest.is_private to skip over functions marked as private
1802     using the underscore naming convention; see its docs for details.
1803 
1804     Advanced tomfoolery:  testmod runs methods of a local instance of
1805     class doctest.Tester, then merges the results into (or creates)
1806     global Tester instance doctest.master.  Methods of doctest.master
1807     can be called directly too, if you want to do something unusual.
1808     Passing report=0 to testmod is especially useful then, to delay
1809     displaying a summary.  Invoke doctest.master.summarize(verbose)
1810     when you're done fiddling.
1811     """
1812     global master
1813 
1814     if isprivate is not None:
1815         warnings.warn("the isprivate argument is deprecated; "
1816                       "examine DocTestFinder.find() lists instead",
1817                       DeprecationWarning)
1818 
1819     # If no module was given, then use __main__.
1820     if m is None:
1821         # DWA - m will still be None if this wasn't invoked from the command
1822         # line, in which case the following TypeError is about as good an error
1823         # as we should expect
1824         m = sys.modules.get('__main__')
1825 
1826     # Check that we were actually given a module.
1827     if not inspect.ismodule(m):
1828         raise TypeError("testmod: module required; %r" % (m,))
1829 
1830     # If no name was given, then use the module's name.
1831     if name is None:
1832         name = m.__name__
1833 
1834     # Find, parse, and run all tests in the given module.
1835     finder = DocTestFinder(_namefilter=isprivate, exclude_empty=exclude_empty)
1836 
1837     if raise_on_error:
1838         runner = DebugRunner(verbose=verbose, optionflags=optionflags)
1839     else:
1840         runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
1841 
1842     for test in finder.find(m, name, globs=globs, extraglobs=extraglobs):
1843         runner.run(test)
1844 
1845     if report:
1846         runner.summarize()
1847 
1848     if master is None:
1849         master = runner
1850     else:
1851         master.merge(runner)
1852 
1853     return runner.failures, runner.tries
1854 
1855 def testfile(filename, module_relative=True, name=None, package=None,
1856              globs=None, verbose=None, report=True, optionflags=0,
1857              extraglobs=None, raise_on_error=False, parser=DocTestParser()):
1858     """
1859     Test examples in the given file.  Return (#failures, #tests).
1860 
1861     Optional keyword arg "module_relative" specifies how filenames
1862     should be interpreted:
1863 
1864       - If "module_relative" is True (the default), then "filename"
1865          specifies a module-relative path.  By default, this path is
1866          relative to the calling module's directory; but if the
1867          "package" argument is specified, then it is relative to that
1868          package.  To ensure os-independence, "filename" should use
1869          "/" characters to separate path segments, and should not
1870          be an absolute path (i.e., it may not begin with "/").
1871 
1872       - If "module_relative" is False, then "filename" specifies an
1873         os-specific path.  The path may be absolute or relative (to
1874         the current working directory).
1875 
1876     Optional keyword arg "name" gives the name of the test; by default
1877     use the file's basename.
1878 
1879     Optional keyword argument "package" is a Python package or the
1880     name of a Python package whose directory should be used as the
1881     base directory for a module relative filename.  If no package is
1882     specified, then the calling module's directory is used as the base
1883     directory for module relative filenames.  It is an error to
1884     specify "package" if "module_relative" is False.
1885 
1886     Optional keyword arg "globs" gives a dict to be used as the globals
1887     when executing examples; by default, use {}.  A copy of this dict
1888     is actually used for each docstring, so that each docstring's
1889     examples start with a clean slate.
1890 
1891     Optional keyword arg "extraglobs" gives a dictionary that should be
1892     merged into the globals that are used to execute examples.  By
1893     default, no extra globals are used.
1894 
1895     Optional keyword arg "verbose" prints lots of stuff if true, prints
1896     only failures if false; by default, it's true iff "-v" is in sys.argv.
1897 
1898     Optional keyword arg "report" prints a summary at the end when true,
1899     else prints nothing at the end.  In verbose mode, the summary is
1900     detailed, else very brief (in fact, empty if all tests passed).
1901 
1902     Optional keyword arg "optionflags" or's together module constants,
1903     and defaults to 0.  Possible values (see the docs for details):
1904 
1905         DONT_ACCEPT_TRUE_FOR_1
1906         DONT_ACCEPT_BLANKLINE
1907         NORMALIZE_WHITESPACE
1908         ELLIPSIS
1909         IGNORE_EXCEPTION_DETAIL
1910         REPORT_UDIFF
1911         REPORT_CDIFF
1912         REPORT_NDIFF
1913         REPORT_ONLY_FIRST_FAILURE
1914 
1915     Optional keyword arg "raise_on_error" raises an exception on the
1916     first unexpected exception or failure. This allows failures to be
1917     post-mortem debugged.
1918 
1919     Optional keyword arg "parser" specifies a DocTestParser (or
1920     subclass) that should be used to extract tests from the files.
1921 
1922     Advanced tomfoolery:  testmod runs methods of a local instance of
1923     class doctest.Tester, then merges the results into (or creates)
1924     global Tester instance doctest.master.  Methods of doctest.master
1925     can be called directly too, if you want to do something unusual.
1926     Passing report=0 to testmod is especially useful then, to delay
1927     displaying a summary.  Invoke doctest.master.summarize(verbose)
1928     when you're done fiddling.
1929     """
1930     global master
1931 
1932     if package and not module_relative:
1933         raise ValueError("Package may only be specified for module-"
1934                          "relative paths.")
1935 
1936     # Relativize the path
1937     if module_relative:
1938         package = _normalize_module(package)
1939         filename = _module_relative_path(package, filename)
1940 
1941     # If no name was given, then use the file's name.
1942     if name is None:
1943         name = os.path.basename(filename)
1944 
1945     # Assemble the globals.
1946     if globs is None:
1947         globs = {}
1948     else:
1949         globs = globs.copy()
1950     if extraglobs is not None:
1951         globs.update(extraglobs)
1952 
1953     if raise_on_error:
1954         runner = DebugRunner(verbose=verbose, optionflags=optionflags)
1955     else:
1956         runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
1957 
1958     # Read the file, convert it to a test, and run it.
1959     s = open(filename).read()
1960     test = parser.get_doctest(s, globs, name, filename, 0)
1961     runner.run(test)
1962 
1963     if report:
1964         runner.summarize()
1965 
1966     if master is None:
1967         master = runner
1968     else:
1969         master.merge(runner)
1970 
1971     return runner.failures, runner.tries
1972 
1973 def run_docstring_examples(f, globs, verbose=False, name="NoName",
1974                            compileflags=None, optionflags=0):
1975     """
1976     Test examples in the given object's docstring (`f`), using `globs`
1977     as globals.  Optional argument `name` is used in failure messages.
1978     If the optional argument `verbose` is true, then generate output
1979     even if there are no failures.
1980 
1981     `compileflags` gives the set of flags that should be used by the
1982     Python compiler when running the examples.  If not specified, then
1983     it will default to the set of future-import flags that apply to
1984     `globs`.
1985 
1986     Optional keyword arg `optionflags` specifies options for the
1987     testing and output.  See the documentation for `testmod` for more
1988     information.
1989     """
1990     # Find, parse, and run all tests in the given module.
1991     finder = DocTestFinder(verbose=verbose, recurse=False)
1992     runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
1993     for test in finder.find(f, name, globs=globs):
1994         runner.run(test, compileflags=compileflags)
1995 
1996 ######################################################################
1997 ## 7. Tester
1998 ######################################################################
1999 # This is provided only for backwards compatibility.  It's not
2000 # actually used in any way.
2001 
2002 class Tester:
2003     def __init__(self, mod=None, globs=None, verbose=None,
2004                  isprivate=None, optionflags=0):
2005 
2006         warnings.warn("class Tester is deprecated; "
2007                       "use class doctest.DocTestRunner instead",
2008                       DeprecationWarning, stacklevel=2)
2009         if mod is None and globs is None:
2010             raise TypeError("Tester.__init__: must specify mod or globs")
2011         if mod is not None and not inspect.ismodule(mod):
2012             raise TypeError("Tester.__init__: mod must be a module; %r" %
2013                             (mod,))
2014         if globs is None:
2015             globs = mod.__dict__
2016         self.globs = globs
2017 
2018         self.verbose = verbose
2019         self.isprivate = isprivate
2020         self.optionflags = optionflags
2021         self.testfinder = DocTestFinder(_namefilter=isprivate)
2022         self.testrunner = DocTestRunner(verbose=verbose,
2023                                         optionflags=optionflags)
2024 
2025     def runstring(self, s, name):
2026         test = DocTestParser().get_doctest(s, self.globs, name, None, None)
2027         if self.verbose:
2028             print "Running string", name
2029         (f,t) = self.testrunner.run(test)
2030         if self.verbose:
2031             print f, "of", t, "examples failed in string", name
2032         return (f,t)
2033 
2034     def rundoc(self, object, name=None, module=None):
2035         f = t = 0
2036         tests = self.testfinder.find(object, name, module=module,
2037                                      globs=self.globs)
2038         for test in tests:
2039             (f2, t2) = self.testrunner.run(test)
2040             (f,t) = (f+f2, t+t2)
2041         return (f,t)
2042 
2043     def rundict(self, d, name, module=None):
2044         import new
2045         m = new.module(name)
2046         m.__dict__.update(d)
2047         if module is None:
2048             module = False
2049         return self.rundoc(m, name, module)
2050 
2051     def run__test__(self, d, name):
2052         import new
2053         m = new.module(name)
2054         m.__test__ = d
2055         return self.rundoc(m, name)
2056 
2057     def summarize(self, verbose=None):
2058         return self.testrunner.summarize(verbose)
2059 
2060     def merge(self, other):
2061         self.testrunner.merge(other.testrunner)
2062 
2063 ######################################################################
2064 ## 8. Unittest Support
2065 ######################################################################
2066 
2067 _unittest_reportflags = 0
2068 
2069 def set_unittest_reportflags(flags):
2070     """Sets the unittest option flags.
2071 
2072     The old flag is returned so that a runner could restore the old
2073     value if it wished to:
2074 
2075       >>> old = _unittest_reportflags
2076       >>> set_unittest_reportflags(REPORT_NDIFF |
2077       ...                          REPORT_ONLY_FIRST_FAILURE) == old
2078       True
2079 
2080       >>> import doctest
2081       >>> doctest._unittest_reportflags == (REPORT_NDIFF |
2082       ...                                   REPORT_ONLY_FIRST_FAILURE)
2083       True
2084 
2085     Only reporting flags can be set:
2086 
2087       >>> set_unittest_reportflags(ELLIPSIS)
2088       Traceback (most recent call last):
2089       ...
2090       ValueError: ('Only reporting flags allowed', 8)
2091 
2092       >>> set_unittest_reportflags(old) == (REPORT_NDIFF |
2093       ...                                   REPORT_ONLY_FIRST_FAILURE)
2094       True
2095     """
2096     global _unittest_reportflags
2097 
2098     if (flags & REPORTING_FLAGS) != flags:
2099         raise ValueError("Only reporting flags allowed", flags)
2100     old = _unittest_reportflags
2101     _unittest_reportflags = flags
2102     return old
2103 
2104 
2105 class DocTestCase(unittest.TestCase):
2106 
2107     def __init__(self, test, optionflags=0, setUp=None, tearDown=None,
2108                  checker=None):
2109 
2110         unittest.TestCase.__init__(self)
2111         self._dt_optionflags = optionflags
2112         self._dt_checker = checker
2113         self._dt_test = test
2114         self._dt_setUp = setUp
2115         self._dt_tearDown = tearDown
2116 
2117     def setUp(self):
2118         test = self._dt_test
2119 
2120         if self._dt_setUp is not None:
2121             self._dt_setUp(test)
2122 
2123     def tearDown(self):
2124         test = self._dt_test
2125 
2126         if self._dt_tearDown is not None:
2127             self._dt_tearDown(test)
2128 
2129         test.globs.clear()
2130 
2131     def runTest(self):
2132         test = self._dt_test
2133         old = sys.stdout
2134         new = StringIO()
2135         optionflags = self._dt_optionflags
2136 
2137         if not (optionflags & REPORTING_FLAGS):
2138             # The option flags don't include any reporting flags,
2139             # so add the default reporting flags
2140             optionflags |= _unittest_reportflags
2141 
2142         runner = DocTestRunner(optionflags=optionflags,
2143                                checker=self._dt_checker, verbose=False)
2144 
2145         try:
2146             runner.DIVIDER = "-"*70
2147             failures, tries = runner.run(
2148                 test, out=new.write, clear_globs=False)
2149         finally:
2150             sys.stdout = old
2151 
2152         if failures:
2153             raise self.failureException(self.format_failure(new.getvalue()))
2154 
2155     def format_failure(self, err):
2156         test = self._dt_test
2157         if test.lineno is None:
2158             lineno = 'unknown line number'
2159         else:
2160             lineno = '%s' % test.lineno
2161         lname = '.'.join(test.name.split('.')[-1:])
2162         return ('Failed doctest test for %s\n'
2163                 '  File "%s", line %s, in %s\n\n%s'
2164                 % (test.name, test.filename, lineno, lname, err)
2165                 )
2166 
2167     def debug(self):
2168         r"""Run the test case without results and without catching exceptions
2169 
2170            The unit test framework includes a debug method on test cases
2171            and test suites to support post-mortem debugging.  The test code
2172            is run in such a way that errors are not caught.  This way a
2173            caller can catch the errors and initiate post-mortem debugging.
2174 
2175            The DocTestCase provides a debug method that raises
2176            UnexpectedException errors if there is an unexepcted
2177            exception:
2178 
2179              >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
2180              ...                {}, 'foo', 'foo.py', 0)
2181              >>> case = DocTestCase(test)
2182              >>> try:
2183              ...     case.debug()
2184              ... except UnexpectedException, failure:
2185              ...     pass
2186 
2187            The UnexpectedException contains the test, the example, and
2188            the original exception:
2189 
2190              >>> failure.test is test
2191              True
2192 
2193              >>> failure.example.want
2194              '42\n'
2195 
2196              >>> exc_info = failure.exc_info
2197              >>> raise exc_info[0], exc_info[1], exc_info[2]
2198              Traceback (most recent call last):
2199              ...
2200              KeyError
2201 
2202            If the output doesn't match, then a DocTestFailure is raised:
2203 
2204              >>> test = DocTestParser().get_doctest('''
2205              ...      >>> x = 1
2206              ...      >>> x
2207              ...      2
2208              ...      ''', {}, 'foo', 'foo.py', 0)
2209              >>> case = DocTestCase(test)
2210 
2211              >>> try:
2212              ...    case.debug()
2213              ... except DocTestFailure, failure:
2214              ...    pass
2215 
2216            DocTestFailure objects provide access to the test:
2217 
2218              >>> failure.test is test
2219              True
2220 
2221            As well as to the example:
2222 
2223              >>> failure.example.want
2224              '2\n'
2225 
2226            and the actual output:
2227 
2228              >>> failure.got
2229              '1\n'
2230 
2231            """
2232 
2233         self.setUp()
2234         runner = DebugRunner(optionflags=self._dt_optionflags,
2235                              checker=self._dt_checker, verbose=False)
2236         runner.run(self._dt_test)
2237         self.tearDown()
2238 
2239     def id(self):
2240         return self._dt_test.name
2241 
2242     def __repr__(self):
2243         name = self._dt_test.name.split('.')
2244         return "%s (%s)" % (name[-1], '.'.join(name[:-1]))
2245 
2246     __str__ = __repr__
2247 
2248     def shortDescription(self):
2249         return "Doctest: " + self._dt_test.name
2250 
2251 def DocTestSuite(module=None, globs=None, extraglobs=None, test_finder=None,
2252                  **options):
2253     """
2254     Convert doctest tests for a module to a unittest test suite.
2255 
2256     This converts each documentation string in a module that
2257     contains doctest tests to a unittest test case.  If any of the
2258     tests in a doc string fail, then the test case fails.  An exception
2259     is raised showing the name of the file containing the test and a
2260     (sometimes approximate) line number.
2261 
2262     The `module` argument provides the module to be tested.  The argument
2263     can be either a module or a module name.
2264 
2265     If no argument is given, the calling module is used.
2266 
2267     A number of options may be provided as keyword arguments:
2268 
2269     setUp
2270       A set-up function.  This is called before running the
2271       tests in each file. The setUp function will be passed a DocTest
2272       object.  The setUp function can access the test globals as the
2273       globs attribute of the test passed.
2274 
2275     tearDown
2276       A tear-down function.  This is called after running the
2277       tests in each file.  The tearDown function will be passed a DocTest
2278       object.  The tearDown function can access the test globals as the
2279       globs attribute of the test passed.
2280 
2281     globs
2282       A dictionary containing initial global variables for the tests.
2283 
2284     optionflags
2285        A set of doctest option flags expressed as an integer.
2286     """
2287 
2288     if test_finder is None:
2289         test_finder = DocTestFinder()
2290 
2291     module = _normalize_module(module)
2292     tests = test_finder.find(module, globs=globs, extraglobs=extraglobs)
2293     if globs is None:
2294         globs = module.__dict__
2295     if not tests:
2296         # Why do we want to do this? Because it reveals a bug that might
2297         # otherwise be hidden.
2298         raise ValueError(module, "has no tests")
2299 
2300     tests.sort()
2301     suite = unittest.TestSuite()
2302     for test in tests:
2303         if len(test.examples) == 0:
2304             continue
2305         if not test.filename:
2306             filename = module.__file__
2307             if filename[-4:] in (".pyc", ".pyo"):
2308                 filename = filename[:-1]
2309             test.filename = filename
2310         suite.addTest(DocTestCase(test, **options))
2311 
2312     return suite
2313 
2314 class DocFileCase(DocTestCase):
2315 
2316     def id(self):
2317         return '_'.join(self._dt_test.name.split('.'))
2318 
2319     def __repr__(self):
2320         return self._dt_test.filename
2321     __str__ = __repr__
2322 
2323     def format_failure(self, err):
2324         return ('Failed doctest test for %s\n  File "%s", line 0\n\n%s'
2325                 % (self._dt_test.name, self._dt_test.filename, err)
2326                 )
2327 
2328 def DocFileTest(path, module_relative=True, package=None,
2329                 globs=None, parser=DocTestParser(), **options):
2330     if globs is None:
2331         globs = {}
2332 
2333     if package and not module_relative:
2334         raise ValueError("Package may only be specified for module-"
2335                          "relative paths.")
2336 
2337     # Relativize the path.
2338     if module_relative:
2339         package = _normalize_module(package)
2340         path = _module_relative_path(package, path)
2341 
2342     # Find the file and read it.
2343     name = os.path.basename(path)
2344     doc = open(path).read()
2345 
2346     # Convert it to a test, and wrap it in a DocFileCase.
2347     test = parser.get_doctest(doc, globs, name, path, 0)
2348     return DocFileCase(test, **options)
2349 
2350 def DocFileSuite(*paths, **kw):
2351     """A unittest suite for one or more doctest files.
2352 
2353     The path to each doctest file is given as a string; the
2354     interpretation of that string depends on the keyword argument
2355     "module_relative".
2356 
2357     A number of options may be provided as keyword arguments:
2358 
2359     module_relative
2360       If "module_relative" is True, then the given file paths are
2361       interpreted as os-independent module-relative paths.  By
2362       default, these paths are relative to the calling module's
2363       directory; but if the "package" argument is specified, then
2364       they are relative to that package.  To ensure os-independence,
2365       "filename" should use "/" characters to separate path
2366       segments, and may not be an absolute path (i.e., it may not
2367       begin with "/").
2368 
2369       If "module_relative" is False, then the given file paths are
2370       interpreted as os-specific paths.  These paths may be absolute
2371       or relative (to the current working directory).
2372 
2373     package
2374       A Python package or the name of a Python package whose directory
2375       should be used as the base directory for module relative paths.
2376       If "package" is not specified, then the calling module's
2377       directory is used as the base directory for module relative
2378       filenames.  It is an error to specify "package" if
2379       "module_relative" is False.
2380 
2381     setUp
2382       A set-up function.  This is called before running the
2383       tests in each file. The setUp function will be passed a DocTest
2384       object.  The setUp function can access the test globals as the
2385       globs attribute of the test passed.
2386 
2387     tearDown
2388       A tear-down function.  This is called after running the
2389       tests in each file.  The tearDown function will be passed a DocTest
2390       object.  The tearDown function can access the test globals as the
2391       globs attribute of the test passed.
2392 
2393     globs
2394       A dictionary containing initial global variables for the tests.
2395 
2396     optionflags
2397       A set of doctest option flags expressed as an integer.
2398 
2399     parser
2400       A DocTestParser (or subclass) that should be used to extract
2401       tests from the files.
2402     """
2403     suite = unittest.TestSuite()
2404 
2405     # We do this here so that _normalize_module is called at the right
2406     # level.  If it were called in DocFileTest, then this function
2407     # would be the caller and we might guess the package incorrectly.
2408     if kw.get('module_relative', True):
2409         kw['package'] = _normalize_module(kw.get('package'))
2410 
2411     for path in paths:
2412         suite.addTest(DocFileTest(path, **kw))
2413 
2414     return suite
2415 
2416 ######################################################################
2417 ## 9. Debugging Support
2418 ######################################################################
2419 
2420 def script_from_examples(s):
2421     r"""Extract script from text with examples.
2422 
2423        Converts text with examples to a Python script.  Example input is
2424        converted to regular code.  Example output and all other words
2425        are converted to comments:
2426 
2427        >>> text = '''
2428        ...       Here are examples of simple math.
2429        ...
2430        ...           Python has super accurate integer addition
2431        ...
2432        ...           >>> 2 + 2
2433        ...           5
2434        ...
2435        ...           And very friendly error messages:
2436        ...
2437        ...           >>> 1/0
2438        ...           To Infinity
2439        ...           And
2440        ...           Beyond
2441        ...
2442        ...           You can use logic if you want:
2443        ...
2444        ...           >>> if 0:
2445        ...           ...    blah
2446        ...           ...    blah
2447        ...           ...
2448        ...
2449        ...           Ho hum
2450        ...           '''
2451 
2452        >>> print script_from_examples(text)
2453        # Here are examples of simple math.
2454        #
2455        #     Python has super accurate integer addition
2456        #
2457        2 + 2
2458        # Expected:
2459        ## 5
2460        #
2461        #     And very friendly error messages:
2462        #
2463        1/0
2464        # Expected:
2465        ## To Infinity
2466        ## And
2467        ## Beyond
2468        #
2469        #     You can use logic if you want:
2470        #
2471        if 0:
2472           blah
2473           blah
2474        #
2475        #     Ho hum
2476        """
2477     output = []
2478     for piece in DocTestParser().parse(s):
2479         if isinstance(piece, Example):
2480             # Add the example's source code (strip trailing NL)
2481             output.append(piece.source[:-1])
2482             # Add the expected output:
2483             want = piece.want
2484             if want:
2485                 output.append('# Expected:')
2486                 output += ['## '+l for l in want.split('\n')[:-1]]
2487         else:
2488             # Add non-example text.
2489             output += [_comment_line(l)
2490                        for l in piece.split('\n')[:-1]]
2491 
2492     # Trim junk on both ends.
2493     while output and output[-1] == '#':
2494         output.pop()
2495     while output and output[0] == '#':
2496         output.pop(0)
2497     # Combine the output, and return it.
2498     return '\n'.join(output)
2499 
2500 def testsource(module, name):
2501     """Extract the test sources from a doctest docstring as a script.
2502 
2503     Provide the module (or dotted name of the module) containing the
2504     test to be debugged and the name (within the module) of the object
2505     with the doc string with tests to be debugged.
2506     """
2507     module = _normalize_module(module)
2508     tests = DocTestFinder().find(module)
2509     test = [t for t in tests if t.name == name]
2510     if not test:
2511         raise ValueError(name, "not found in tests")
2512     test = test[0]
2513     testsrc = script_from_examples(test.docstring)
2514     return testsrc
2515 
2516 def debug_src(src, pm=False, globs=None):
2517     """Debug a single doctest docstring, in argument `src`'"""
2518     testsrc = script_from_examples(src)
2519     debug_script(testsrc, pm, globs)
2520 
2521 def debug_script(src, pm=False, globs=None):
2522     "Debug a test script.  `src` is the script, as a string."
2523     import pdb
2524 
2525     # Note that tempfile.NameTemporaryFile() cannot be used.  As the
2526     # docs say, a file so created cannot be opened by name a second time
2527     # on modern Windows boxes, and execfile() needs to open it.
2528     srcfilename = tempfile.mktemp(".py", "doctestdebug")
2529     f = open(srcfilename, 'w')
2530     f.write(src)
2531     f.close()
2532 
2533     try:
2534         if globs:
2535             globs = globs.copy()
2536         else:
2537             globs = {}
2538 
2539         if pm:
2540             try:
2541                 execfile(srcfilename, globs, globs)
2542             except:
2543                 print sys.exc_info()[1]
2544                 pdb.post_mortem(sys.exc_info()[2])
2545         else:
2546             # Note that %r is vital here.  '%s' instead can, e.g., cause
2547             # backslashes to get treated as metacharacters on Windows.
2548             pdb.run("execfile(%r)" % srcfilename, globs, globs)
2549 
2550     finally:
2551         os.remove(srcfilename)
2552 
2553 def debug(module, name, pm=False):
2554     """Debug a single doctest docstring.
2555 
2556     Provide the module (or dotted name of the module) containing the
2557     test to be debugged and the name (within the module) of the object
2558     with the docstring with tests to be debugged.
2559     """
2560     module = _normalize_module(module)
2561     testsrc = testsource(module, name)
2562     debug_script(testsrc, pm, module.__dict__)
2563 
2564 ######################################################################
2565 ## 10. Example Usage
2566 ######################################################################
2567 class _TestClass:
2568     """
2569     A pointless class, for sanity-checking of docstring testing.
2570 
2571     Methods:
2572         square()
2573         get()
2574 
2575     >>> _TestClass(13).get() + _TestClass(-12).get()
2576     1
2577     >>> hex(_TestClass(13).square().get())
2578     '0xa9'
2579     """
2580 
2581     def __init__(self, val):
2582         """val -> _TestClass object with associated value val.
2583 
2584         >>> t = _TestClass(123)
2585         >>> print t.get()
2586         123
2587         """
2588 
2589         self.val = val
2590 
2591     def square(self):
2592         """square() -> square TestClass's associated value
2593 
2594         >>> _TestClass(13).square().get()
2595         169
2596         """
2597 
2598         self.val = self.val ** 2
2599         return self
2600 
2601     def get(self):
2602         """get() -> return TestClass's associated value.
2603 
2604         >>> x = _TestClass(-42)
2605         >>> print x.get()
2606         -42
2607         """
2608 
2609         return self.val
2610 
2611 __test__ = {"_TestClass": _TestClass,
2612             "string": r"""
2613                       Example of a string object, searched as-is.
2614                       >>> x = 1; y = 2
2615                       >>> x + y, x * y
2616                       (3, 2)
2617                       """,
2618 
2619             "bool-int equivalence": r"""
2620                                     In 2.2, boolean expressions displayed
2621                                     0 or 1.  By default, we still accept
2622                                     them.  This can be disabled by passing
2623                                     DONT_ACCEPT_TRUE_FOR_1 to the new
2624                                     optionflags argument.
2625                                     >>> 4 == 4
2626                                     1
2627                                     >>> 4 == 4
2628                                     True
2629                                     >>> 4 > 4
2630                                     0
2631                                     >>> 4 > 4
2632                                     False
2633                                     """,
2634 
2635             "blank lines": r"""
2636                 Blank lines can be marked with <BLANKLINE>:
2637                     >>> print 'foo\n\nbar\n'
2638                     foo
2639                     <BLANKLINE>
2640                     bar
2641                     <BLANKLINE>
2642             """,
2643 
2644             "ellipsis": r"""
2645                 If the ellipsis flag is used, then '...' can be used to
2646                 elide substrings in the desired output:
2647                     >>> print range(1000) #doctest: +ELLIPSIS
2648                     [0, 1, 2, ..., 999]
2649             """,
2650 
2651             "whitespace normalization": r"""
2652                 If the whitespace normalization flag is used, then
2653                 differences in whitespace are ignored.
2654                     >>> print range(30) #doctest: +NORMALIZE_WHITESPACE
2655                     [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14,
2656                      15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26,
2657                      27, 28, 29]
2658             """,
2659            }
2660 
2661 def _test():
2662     r = unittest.TextTestRunner()
2663     r.run(DocTestSuite())
2664 
2665 if __name__ == "__main__":
2666     _test()
2667