+++ /dev/null
-# Module doctest.\r
-# Released to the public domain 16-Jan-2001, by Tim Peters (tim@python.org).\r
-# Major enhancements and refactoring by:\r
-# Jim Fulton\r
-# Edward Loper\r
-\r
-# Provided as-is; use at your own risk; no warranty; no promises; enjoy!\r
-\r
-r"""Module doctest -- a framework for running examples in docstrings.\r
-\r
-In simplest use, end each module M to be tested with:\r
-\r
-def _test():\r
- import doctest\r
- doctest.testmod()\r
-\r
-if __name__ == "__main__":\r
- _test()\r
-\r
-Then running the module as a script will cause the examples in the\r
-docstrings to get executed and verified:\r
-\r
-python M.py\r
-\r
-This won't display anything unless an example fails, in which case the\r
-failing example(s) and the cause(s) of the failure(s) are printed to stdout\r
-(why not stderr? because stderr is a lame hack <0.2 wink>), and the final\r
-line of output is "Test failed.".\r
-\r
-Run it with the -v switch instead:\r
-\r
-python M.py -v\r
-\r
-and a detailed report of all examples tried is printed to stdout, along\r
-with assorted summaries at the end.\r
-\r
-You can force verbose mode by passing "verbose=True" to testmod, or prohibit\r
-it by passing "verbose=False". In either of those cases, sys.argv is not\r
-examined by testmod.\r
-\r
-There are a variety of other ways to run doctests, including integration\r
-with the unittest framework, and support for running non-Python text\r
-files containing doctests. There are also many ways to override parts\r
-of doctest's default behaviors. See the Library Reference Manual for\r
-details.\r
-"""\r
-\r
-__docformat__ = 'reStructuredText en'\r
-\r
-__all__ = [\r
- # 0, Option Flags\r
- 'register_optionflag',\r
- 'DONT_ACCEPT_TRUE_FOR_1',\r
- 'DONT_ACCEPT_BLANKLINE',\r
- 'NORMALIZE_WHITESPACE',\r
- 'ELLIPSIS',\r
- 'SKIP',\r
- 'IGNORE_EXCEPTION_DETAIL',\r
- 'COMPARISON_FLAGS',\r
- 'REPORT_UDIFF',\r
- 'REPORT_CDIFF',\r
- 'REPORT_NDIFF',\r
- 'REPORT_ONLY_FIRST_FAILURE',\r
- 'REPORTING_FLAGS',\r
- # 1. Utility Functions\r
- # 2. Example & DocTest\r
- 'Example',\r
- 'DocTest',\r
- # 3. Doctest Parser\r
- 'DocTestParser',\r
- # 4. Doctest Finder\r
- 'DocTestFinder',\r
- # 5. Doctest Runner\r
- 'DocTestRunner',\r
- 'OutputChecker',\r
- 'DocTestFailure',\r
- 'UnexpectedException',\r
- 'DebugRunner',\r
- # 6. Test Functions\r
- 'testmod',\r
- 'testfile',\r
- 'run_docstring_examples',\r
- # 7. Tester\r
- 'Tester',\r
- # 8. Unittest Support\r
- 'DocTestSuite',\r
- 'DocFileSuite',\r
- 'set_unittest_reportflags',\r
- # 9. Debugging Support\r
- 'script_from_examples',\r
- 'testsource',\r
- 'debug_src',\r
- 'debug',\r
-]\r
-\r
-import __future__\r
-\r
-import sys, traceback, inspect, linecache, os, re\r
-import unittest, difflib, pdb, tempfile\r
-import warnings\r
-from StringIO import StringIO\r
-from collections import namedtuple\r
-\r
-TestResults = namedtuple('TestResults', 'failed attempted')\r
-\r
-# There are 4 basic classes:\r
-# - Example: a <source, want> pair, plus an intra-docstring line number.\r
-# - DocTest: a collection of examples, parsed from a docstring, plus\r
-# info about where the docstring came from (name, filename, lineno).\r
-# - DocTestFinder: extracts DocTests from a given object's docstring and\r
-# its contained objects' docstrings.\r
-# - DocTestRunner: runs DocTest cases, and accumulates statistics.\r
-#\r
-# So the basic picture is:\r
-#\r
-# list of:\r
-# +------+ +---------+ +-------+\r
-# |object| --DocTestFinder-> | DocTest | --DocTestRunner-> |results|\r
-# +------+ +---------+ +-------+\r
-# | Example |\r
-# | ... |\r
-# | Example |\r
-# +---------+\r
-\r
-# Option constants.\r
-\r
-OPTIONFLAGS_BY_NAME = {}\r
-def register_optionflag(name):\r
- # Create a new flag unless `name` is already known.\r
- return OPTIONFLAGS_BY_NAME.setdefault(name, 1 << len(OPTIONFLAGS_BY_NAME))\r
-\r
-DONT_ACCEPT_TRUE_FOR_1 = register_optionflag('DONT_ACCEPT_TRUE_FOR_1')\r
-DONT_ACCEPT_BLANKLINE = register_optionflag('DONT_ACCEPT_BLANKLINE')\r
-NORMALIZE_WHITESPACE = register_optionflag('NORMALIZE_WHITESPACE')\r
-ELLIPSIS = register_optionflag('ELLIPSIS')\r
-SKIP = register_optionflag('SKIP')\r
-IGNORE_EXCEPTION_DETAIL = register_optionflag('IGNORE_EXCEPTION_DETAIL')\r
-\r
-COMPARISON_FLAGS = (DONT_ACCEPT_TRUE_FOR_1 |\r
- DONT_ACCEPT_BLANKLINE |\r
- NORMALIZE_WHITESPACE |\r
- ELLIPSIS |\r
- SKIP |\r
- IGNORE_EXCEPTION_DETAIL)\r
-\r
-REPORT_UDIFF = register_optionflag('REPORT_UDIFF')\r
-REPORT_CDIFF = register_optionflag('REPORT_CDIFF')\r
-REPORT_NDIFF = register_optionflag('REPORT_NDIFF')\r
-REPORT_ONLY_FIRST_FAILURE = register_optionflag('REPORT_ONLY_FIRST_FAILURE')\r
-\r
-REPORTING_FLAGS = (REPORT_UDIFF |\r
- REPORT_CDIFF |\r
- REPORT_NDIFF |\r
- REPORT_ONLY_FIRST_FAILURE)\r
-\r
-# Special string markers for use in `want` strings:\r
-BLANKLINE_MARKER = '<BLANKLINE>'\r
-ELLIPSIS_MARKER = '...'\r
-\r
-######################################################################\r
-## Table of Contents\r
-######################################################################\r
-# 1. Utility Functions\r
-# 2. Example & DocTest -- store test cases\r
-# 3. DocTest Parser -- extracts examples from strings\r
-# 4. DocTest Finder -- extracts test cases from objects\r
-# 5. DocTest Runner -- runs test cases\r
-# 6. Test Functions -- convenient wrappers for testing\r
-# 7. Tester Class -- for backwards compatibility\r
-# 8. Unittest Support\r
-# 9. Debugging Support\r
-# 10. Example Usage\r
-\r
-######################################################################\r
-## 1. Utility Functions\r
-######################################################################\r
-\r
-def _extract_future_flags(globs):\r
- """\r
- Return the compiler-flags associated with the future features that\r
- have been imported into the given namespace (globs).\r
- """\r
- flags = 0\r
- for fname in __future__.all_feature_names:\r
- feature = globs.get(fname, None)\r
- if feature is getattr(__future__, fname):\r
- flags |= feature.compiler_flag\r
- return flags\r
-\r
-def _normalize_module(module, depth=2):\r
- """\r
- Return the module specified by `module`. In particular:\r
- - If `module` is a module, then return module.\r
- - If `module` is a string, then import and return the\r
- module with that name.\r
- - If `module` is None, then return the calling module.\r
- The calling module is assumed to be the module of\r
- the stack frame at the given depth in the call stack.\r
- """\r
- if inspect.ismodule(module):\r
- return module\r
- elif isinstance(module, (str, unicode)):\r
- return __import__(module, globals(), locals(), ["*"])\r
- elif module is None:\r
- return sys.modules[sys._getframe(depth).f_globals['__name__']]\r
- else:\r
- raise TypeError("Expected a module, string, or None")\r
-\r
-def _load_testfile(filename, package, module_relative):\r
- if module_relative:\r
- package = _normalize_module(package, 3)\r
- filename = _module_relative_path(package, filename)\r
- if hasattr(package, '__loader__'):\r
- if hasattr(package.__loader__, 'get_data'):\r
- file_contents = package.__loader__.get_data(filename)\r
- # get_data() opens files as 'rb', so one must do the equivalent\r
- # conversion as universal newlines would do.\r
- return file_contents.replace(os.linesep, '\n'), filename\r
- with open(filename) as f:\r
- return f.read(), filename\r
-\r
-# Use sys.stdout encoding for ouput.\r
-_encoding = getattr(sys.__stdout__, 'encoding', None) or 'utf-8'\r
-\r
-def _indent(s, indent=4):\r
- """\r
- Add the given number of space characters to the beginning of\r
- every non-blank line in `s`, and return the result.\r
- If the string `s` is Unicode, it is encoded using the stdout\r
- encoding and the `backslashreplace` error handler.\r
- """\r
- if isinstance(s, unicode):\r
- s = s.encode(_encoding, 'backslashreplace')\r
- # This regexp matches the start of non-blank lines:\r
- return re.sub('(?m)^(?!$)', indent*' ', s)\r
-\r
-def _exception_traceback(exc_info):\r
- """\r
- Return a string containing a traceback message for the given\r
- exc_info tuple (as returned by sys.exc_info()).\r
- """\r
- # Get a traceback message.\r
- excout = StringIO()\r
- exc_type, exc_val, exc_tb = exc_info\r
- traceback.print_exception(exc_type, exc_val, exc_tb, file=excout)\r
- return excout.getvalue()\r
-\r
-# Override some StringIO methods.\r
-class _SpoofOut(StringIO):\r
- def getvalue(self):\r
- result = StringIO.getvalue(self)\r
- # If anything at all was written, make sure there's a trailing\r
- # newline. There's no way for the expected output to indicate\r
- # that a trailing newline is missing.\r
- if result and not result.endswith("\n"):\r
- result += "\n"\r
- # Prevent softspace from screwing up the next test case, in\r
- # case they used print with a trailing comma in an example.\r
- if hasattr(self, "softspace"):\r
- del self.softspace\r
- return result\r
-\r
- def truncate(self, size=None):\r
- StringIO.truncate(self, size)\r
- if hasattr(self, "softspace"):\r
- del self.softspace\r
- if not self.buf:\r
- # Reset it to an empty string, to make sure it's not unicode.\r
- self.buf = ''\r
-\r
-# Worst-case linear-time ellipsis matching.\r
-def _ellipsis_match(want, got):\r
- """\r
- Essentially the only subtle case:\r
- >>> _ellipsis_match('aa...aa', 'aaa')\r
- False\r
- """\r
- if ELLIPSIS_MARKER not in want:\r
- return want == got\r
-\r
- # Find "the real" strings.\r
- ws = want.split(ELLIPSIS_MARKER)\r
- assert len(ws) >= 2\r
-\r
- # Deal with exact matches possibly needed at one or both ends.\r
- startpos, endpos = 0, len(got)\r
- w = ws[0]\r
- if w: # starts with exact match\r
- if got.startswith(w):\r
- startpos = len(w)\r
- del ws[0]\r
- else:\r
- return False\r
- w = ws[-1]\r
- if w: # ends with exact match\r
- if got.endswith(w):\r
- endpos -= len(w)\r
- del ws[-1]\r
- else:\r
- return False\r
-\r
- if startpos > endpos:\r
- # Exact end matches required more characters than we have, as in\r
- # _ellipsis_match('aa...aa', 'aaa')\r
- return False\r
-\r
- # For the rest, we only need to find the leftmost non-overlapping\r
- # match for each piece. If there's no overall match that way alone,\r
- # there's no overall match period.\r
- for w in ws:\r
- # w may be '' at times, if there are consecutive ellipses, or\r
- # due to an ellipsis at the start or end of `want`. That's OK.\r
- # Search for an empty string succeeds, and doesn't change startpos.\r
- startpos = got.find(w, startpos, endpos)\r
- if startpos < 0:\r
- return False\r
- startpos += len(w)\r
-\r
- return True\r
-\r
-def _comment_line(line):\r
- "Return a commented form of the given line"\r
- line = line.rstrip()\r
- if line:\r
- return '# '+line\r
- else:\r
- return '#'\r
-\r
-class _OutputRedirectingPdb(pdb.Pdb):\r
- """\r
- A specialized version of the python debugger that redirects stdout\r
- to a given stream when interacting with the user. Stdout is *not*\r
- redirected when traced code is executed.\r
- """\r
- def __init__(self, out):\r
- self.__out = out\r
- self.__debugger_used = False\r
- pdb.Pdb.__init__(self, stdout=out)\r
- # still use input() to get user input\r
- self.use_rawinput = 1\r
-\r
- def set_trace(self, frame=None):\r
- self.__debugger_used = True\r
- if frame is None:\r
- frame = sys._getframe().f_back\r
- pdb.Pdb.set_trace(self, frame)\r
-\r
- def set_continue(self):\r
- # Calling set_continue unconditionally would break unit test\r
- # coverage reporting, as Bdb.set_continue calls sys.settrace(None).\r
- if self.__debugger_used:\r
- pdb.Pdb.set_continue(self)\r
-\r
- def trace_dispatch(self, *args):\r
- # Redirect stdout to the given stream.\r
- save_stdout = sys.stdout\r
- sys.stdout = self.__out\r
- # Call Pdb's trace dispatch method.\r
- try:\r
- return pdb.Pdb.trace_dispatch(self, *args)\r
- finally:\r
- sys.stdout = save_stdout\r
-\r
-# [XX] Normalize with respect to os.path.pardir?\r
-def _module_relative_path(module, path):\r
- if not inspect.ismodule(module):\r
- raise TypeError, 'Expected a module: %r' % module\r
- if path.startswith('/'):\r
- raise ValueError, 'Module-relative files may not have absolute paths'\r
-\r
- # Find the base directory for the path.\r
- if hasattr(module, '__file__'):\r
- # A normal module/package\r
- basedir = os.path.split(module.__file__)[0]\r
- elif module.__name__ == '__main__':\r
- # An interactive session.\r
- if len(sys.argv)>0 and sys.argv[0] != '':\r
- basedir = os.path.split(sys.argv[0])[0]\r
- else:\r
- basedir = os.curdir\r
- else:\r
- # A module w/o __file__ (this includes builtins)\r
- raise ValueError("Can't resolve paths relative to the module " +\r
- module + " (it has no __file__)")\r
-\r
- # Combine the base directory and the path.\r
- return os.path.join(basedir, *(path.split('/')))\r
-\r
-######################################################################\r
-## 2. Example & DocTest\r
-######################################################################\r
-## - An "example" is a <source, want> pair, where "source" is a\r
-## fragment of source code, and "want" is the expected output for\r
-## "source." The Example class also includes information about\r
-## where the example was extracted from.\r
-##\r
-## - A "doctest" is a collection of examples, typically extracted from\r
-## a string (such as an object's docstring). The DocTest class also\r
-## includes information about where the string was extracted from.\r
-\r
-class Example:\r
- """\r
- A single doctest example, consisting of source code and expected\r
- output. `Example` defines the following attributes:\r
-\r
- - source: A single Python statement, always ending with a newline.\r
- The constructor adds a newline if needed.\r
-\r
- - want: The expected output from running the source code (either\r
- from stdout, or a traceback in case of exception). `want` ends\r
- with a newline unless it's empty, in which case it's an empty\r
- string. The constructor adds a newline if needed.\r
-\r
- - exc_msg: The exception message generated by the example, if\r
- the example is expected to generate an exception; or `None` if\r
- it is not expected to generate an exception. This exception\r
- message is compared against the return value of\r
- `traceback.format_exception_only()`. `exc_msg` ends with a\r
- newline unless it's `None`. The constructor adds a newline\r
- if needed.\r
-\r
- - lineno: The line number within the DocTest string containing\r
- this Example where the Example begins. This line number is\r
- zero-based, with respect to the beginning of the DocTest.\r
-\r
- - indent: The example's indentation in the DocTest string.\r
- I.e., the number of space characters that preceed the\r
- example's first prompt.\r
-\r
- - options: A dictionary mapping from option flags to True or\r
- False, which is used to override default options for this\r
- example. Any option flags not contained in this dictionary\r
- are left at their default value (as specified by the\r
- DocTestRunner's optionflags). By default, no options are set.\r
- """\r
- def __init__(self, source, want, exc_msg=None, lineno=0, indent=0,\r
- options=None):\r
- # Normalize inputs.\r
- if not source.endswith('\n'):\r
- source += '\n'\r
- if want and not want.endswith('\n'):\r
- want += '\n'\r
- if exc_msg is not None and not exc_msg.endswith('\n'):\r
- exc_msg += '\n'\r
- # Store properties.\r
- self.source = source\r
- self.want = want\r
- self.lineno = lineno\r
- self.indent = indent\r
- if options is None: options = {}\r
- self.options = options\r
- self.exc_msg = exc_msg\r
-\r
-class DocTest:\r
- """\r
- A collection of doctest examples that should be run in a single\r
- namespace. Each `DocTest` defines the following attributes:\r
-\r
- - examples: the list of examples.\r
-\r
- - globs: The namespace (aka globals) that the examples should\r
- be run in.\r
-\r
- - name: A name identifying the DocTest (typically, the name of\r
- the object whose docstring this DocTest was extracted from).\r
-\r
- - filename: The name of the file that this DocTest was extracted\r
- from, or `None` if the filename is unknown.\r
-\r
- - lineno: The line number within filename where this DocTest\r
- begins, or `None` if the line number is unavailable. This\r
- line number is zero-based, with respect to the beginning of\r
- the file.\r
-\r
- - docstring: The string that the examples were extracted from,\r
- or `None` if the string is unavailable.\r
- """\r
- def __init__(self, examples, globs, name, filename, lineno, docstring):\r
- """\r
- Create a new DocTest containing the given examples. The\r
- DocTest's globals are initialized with a copy of `globs`.\r
- """\r
- assert not isinstance(examples, basestring), \\r
- "DocTest no longer accepts str; use DocTestParser instead"\r
- self.examples = examples\r
- self.docstring = docstring\r
- self.globs = globs.copy()\r
- self.name = name\r
- self.filename = filename\r
- self.lineno = lineno\r
-\r
- def __repr__(self):\r
- if len(self.examples) == 0:\r
- examples = 'no examples'\r
- elif len(self.examples) == 1:\r
- examples = '1 example'\r
- else:\r
- examples = '%d examples' % len(self.examples)\r
- return ('<DocTest %s from %s:%s (%s)>' %\r
- (self.name, self.filename, self.lineno, examples))\r
-\r
-\r
- # This lets us sort tests by name:\r
- def __cmp__(self, other):\r
- if not isinstance(other, DocTest):\r
- return -1\r
- return cmp((self.name, self.filename, self.lineno, id(self)),\r
- (other.name, other.filename, other.lineno, id(other)))\r
-\r
-######################################################################\r
-## 3. DocTestParser\r
-######################################################################\r
-\r
-class DocTestParser:\r
- """\r
- A class used to parse strings containing doctest examples.\r
- """\r
- # This regular expression is used to find doctest examples in a\r
- # string. It defines three groups: `source` is the source code\r
- # (including leading indentation and prompts); `indent` is the\r
- # indentation of the first (PS1) line of the source code; and\r
- # `want` is the expected output (including leading indentation).\r
- _EXAMPLE_RE = re.compile(r'''\r
- # Source consists of a PS1 line followed by zero or more PS2 lines.\r
- (?P<source>\r
- (?:^(?P<indent> [ ]*) >>> .*) # PS1 line\r
- (?:\n [ ]* \.\.\. .*)*) # PS2 lines\r
- \n?\r
- # Want consists of any non-blank lines that do not start with PS1.\r
- (?P<want> (?:(?![ ]*$) # Not a blank line\r
- (?![ ]*>>>) # Not a line starting with PS1\r
- .*$\n? # But any other line\r
- )*)\r
- ''', re.MULTILINE | re.VERBOSE)\r
-\r
- # A regular expression for handling `want` strings that contain\r
- # expected exceptions. It divides `want` into three pieces:\r
- # - the traceback header line (`hdr`)\r
- # - the traceback stack (`stack`)\r
- # - the exception message (`msg`), as generated by\r
- # traceback.format_exception_only()\r
- # `msg` may have multiple lines. We assume/require that the\r
- # exception message is the first non-indented line starting with a word\r
- # character following the traceback header line.\r
- _EXCEPTION_RE = re.compile(r"""\r
- # Grab the traceback header. Different versions of Python have\r
- # said different things on the first traceback line.\r
- ^(?P<hdr> Traceback\ \(\r
- (?: most\ recent\ call\ last\r
- | innermost\ last\r
- ) \) :\r
- )\r
- \s* $ # toss trailing whitespace on the header.\r
- (?P<stack> .*?) # don't blink: absorb stuff until...\r
- ^ (?P<msg> \w+ .*) # a line *starts* with alphanum.\r
- """, re.VERBOSE | re.MULTILINE | re.DOTALL)\r
-\r
- # A callable returning a true value iff its argument is a blank line\r
- # or contains a single comment.\r
- _IS_BLANK_OR_COMMENT = re.compile(r'^[ ]*(#.*)?$').match\r
-\r
- def parse(self, string, name='<string>'):\r
- """\r
- Divide the given string into examples and intervening text,\r
- and return them as a list of alternating Examples and strings.\r
- Line numbers for the Examples are 0-based. The optional\r
- argument `name` is a name identifying this string, and is only\r
- used for error messages.\r
- """\r
- string = string.expandtabs()\r
- # If all lines begin with the same indentation, then strip it.\r
- min_indent = self._min_indent(string)\r
- if min_indent > 0:\r
- string = '\n'.join([l[min_indent:] for l in string.split('\n')])\r
-\r
- output = []\r
- charno, lineno = 0, 0\r
- # Find all doctest examples in the string:\r
- for m in self._EXAMPLE_RE.finditer(string):\r
- # Add the pre-example text to `output`.\r
- output.append(string[charno:m.start()])\r
- # Update lineno (lines before this example)\r
- lineno += string.count('\n', charno, m.start())\r
- # Extract info from the regexp match.\r
- (source, options, want, exc_msg) = \\r
- self._parse_example(m, name, lineno)\r
- # Create an Example, and add it to the list.\r
- if not self._IS_BLANK_OR_COMMENT(source):\r
- output.append( Example(source, want, exc_msg,\r
- lineno=lineno,\r
- indent=min_indent+len(m.group('indent')),\r
- options=options) )\r
- # Update lineno (lines inside this example)\r
- lineno += string.count('\n', m.start(), m.end())\r
- # Update charno.\r
- charno = m.end()\r
- # Add any remaining post-example text to `output`.\r
- output.append(string[charno:])\r
- return output\r
-\r
- def get_doctest(self, string, globs, name, filename, lineno):\r
- """\r
- Extract all doctest examples from the given string, and\r
- collect them into a `DocTest` object.\r
-\r
- `globs`, `name`, `filename`, and `lineno` are attributes for\r
- the new `DocTest` object. See the documentation for `DocTest`\r
- for more information.\r
- """\r
- return DocTest(self.get_examples(string, name), globs,\r
- name, filename, lineno, string)\r
-\r
- def get_examples(self, string, name='<string>'):\r
- """\r
- Extract all doctest examples from the given string, and return\r
- them as a list of `Example` objects. Line numbers are\r
- 0-based, because it's most common in doctests that nothing\r
- interesting appears on the same line as opening triple-quote,\r
- and so the first interesting line is called \"line 1\" then.\r
-\r
- The optional argument `name` is a name identifying this\r
- string, and is only used for error messages.\r
- """\r
- return [x for x in self.parse(string, name)\r
- if isinstance(x, Example)]\r
-\r
- def _parse_example(self, m, name, lineno):\r
- """\r
- Given a regular expression match from `_EXAMPLE_RE` (`m`),\r
- return a pair `(source, want)`, where `source` is the matched\r
- example's source code (with prompts and indentation stripped);\r
- and `want` is the example's expected output (with indentation\r
- stripped).\r
-\r
- `name` is the string's name, and `lineno` is the line number\r
- where the example starts; both are used for error messages.\r
- """\r
- # Get the example's indentation level.\r
- indent = len(m.group('indent'))\r
-\r
- # Divide source into lines; check that they're properly\r
- # indented; and then strip their indentation & prompts.\r
- source_lines = m.group('source').split('\n')\r
- self._check_prompt_blank(source_lines, indent, name, lineno)\r
- self._check_prefix(source_lines[1:], ' '*indent + '.', name, lineno)\r
- source = '\n'.join([sl[indent+4:] for sl in source_lines])\r
-\r
- # Divide want into lines; check that it's properly indented; and\r
- # then strip the indentation. Spaces before the last newline should\r
- # be preserved, so plain rstrip() isn't good enough.\r
- want = m.group('want')\r
- want_lines = want.split('\n')\r
- if len(want_lines) > 1 and re.match(r' *$', want_lines[-1]):\r
- del want_lines[-1] # forget final newline & spaces after it\r
- self._check_prefix(want_lines, ' '*indent, name,\r
- lineno + len(source_lines))\r
- want = '\n'.join([wl[indent:] for wl in want_lines])\r
-\r
- # If `want` contains a traceback message, then extract it.\r
- m = self._EXCEPTION_RE.match(want)\r
- if m:\r
- exc_msg = m.group('msg')\r
- else:\r
- exc_msg = None\r
-\r
- # Extract options from the source.\r
- options = self._find_options(source, name, lineno)\r
-\r
- return source, options, want, exc_msg\r
-\r
- # This regular expression looks for option directives in the\r
- # source code of an example. Option directives are comments\r
- # starting with "doctest:". Warning: this may give false\r
- # positives for string-literals that contain the string\r
- # "#doctest:". Eliminating these false positives would require\r
- # actually parsing the string; but we limit them by ignoring any\r
- # line containing "#doctest:" that is *followed* by a quote mark.\r
- _OPTION_DIRECTIVE_RE = re.compile(r'#\s*doctest:\s*([^\n\'"]*)$',\r
- re.MULTILINE)\r
-\r
- def _find_options(self, source, name, lineno):\r
- """\r
- Return a dictionary containing option overrides extracted from\r
- option directives in the given source string.\r
-\r
- `name` is the string's name, and `lineno` is the line number\r
- where the example starts; both are used for error messages.\r
- """\r
- options = {}\r
- # (note: with the current regexp, this will match at most once:)\r
- for m in self._OPTION_DIRECTIVE_RE.finditer(source):\r
- option_strings = m.group(1).replace(',', ' ').split()\r
- for option in option_strings:\r
- if (option[0] not in '+-' or\r
- option[1:] not in OPTIONFLAGS_BY_NAME):\r
- raise ValueError('line %r of the doctest for %s '\r
- 'has an invalid option: %r' %\r
- (lineno+1, name, option))\r
- flag = OPTIONFLAGS_BY_NAME[option[1:]]\r
- options[flag] = (option[0] == '+')\r
- if options and self._IS_BLANK_OR_COMMENT(source):\r
- raise ValueError('line %r of the doctest for %s has an option '\r
- 'directive on a line with no example: %r' %\r
- (lineno, name, source))\r
- return options\r
-\r
- # This regular expression finds the indentation of every non-blank\r
- # line in a string.\r
- _INDENT_RE = re.compile('^([ ]*)(?=\S)', re.MULTILINE)\r
-\r
- def _min_indent(self, s):\r
- "Return the minimum indentation of any non-blank line in `s`"\r
- indents = [len(indent) for indent in self._INDENT_RE.findall(s)]\r
- if len(indents) > 0:\r
- return min(indents)\r
- else:\r
- return 0\r
-\r
- def _check_prompt_blank(self, lines, indent, name, lineno):\r
- """\r
- Given the lines of a source string (including prompts and\r
- leading indentation), check to make sure that every prompt is\r
- followed by a space character. If any line is not followed by\r
- a space character, then raise ValueError.\r
- """\r
- for i, line in enumerate(lines):\r
- if len(line) >= indent+4 and line[indent+3] != ' ':\r
- raise ValueError('line %r of the docstring for %s '\r
- 'lacks blank after %s: %r' %\r
- (lineno+i+1, name,\r
- line[indent:indent+3], line))\r
-\r
- def _check_prefix(self, lines, prefix, name, lineno):\r
- """\r
- Check that every line in the given list starts with the given\r
- prefix; if any line does not, then raise a ValueError.\r
- """\r
- for i, line in enumerate(lines):\r
- if line and not line.startswith(prefix):\r
- raise ValueError('line %r of the docstring for %s has '\r
- 'inconsistent leading whitespace: %r' %\r
- (lineno+i+1, name, line))\r
-\r
-\r
-######################################################################\r
-## 4. DocTest Finder\r
-######################################################################\r
-\r
-class DocTestFinder:\r
- """\r
- A class used to extract the DocTests that are relevant to a given\r
- object, from its docstring and the docstrings of its contained\r
- objects. Doctests can currently be extracted from the following\r
- object types: modules, functions, classes, methods, staticmethods,\r
- classmethods, and properties.\r
- """\r
-\r
- def __init__(self, verbose=False, parser=DocTestParser(),\r
- recurse=True, exclude_empty=True):\r
- """\r
- Create a new doctest finder.\r
-\r
- The optional argument `parser` specifies a class or\r
- function that should be used to create new DocTest objects (or\r
- objects that implement the same interface as DocTest). The\r
- signature for this factory function should match the signature\r
- of the DocTest constructor.\r
-\r
- If the optional argument `recurse` is false, then `find` will\r
- only examine the given object, and not any contained objects.\r
-\r
- If the optional argument `exclude_empty` is false, then `find`\r
- will include tests for objects with empty docstrings.\r
- """\r
- self._parser = parser\r
- self._verbose = verbose\r
- self._recurse = recurse\r
- self._exclude_empty = exclude_empty\r
-\r
- def find(self, obj, name=None, module=None, globs=None, extraglobs=None):\r
- """\r
- Return a list of the DocTests that are defined by the given\r
- object's docstring, or by any of its contained objects'\r
- docstrings.\r
-\r
- The optional parameter `module` is the module that contains\r
- the given object. If the module is not specified or is None, then\r
- the test finder will attempt to automatically determine the\r
- correct module. The object's module is used:\r
-\r
- - As a default namespace, if `globs` is not specified.\r
- - To prevent the DocTestFinder from extracting DocTests\r
- from objects that are imported from other modules.\r
- - To find the name of the file containing the object.\r
- - To help find the line number of the object within its\r
- file.\r
-\r
- Contained objects whose module does not match `module` are ignored.\r
-\r
- If `module` is False, no attempt to find the module will be made.\r
- This is obscure, of use mostly in tests: if `module` is False, or\r
- is None but cannot be found automatically, then all objects are\r
- considered to belong to the (non-existent) module, so all contained\r
- objects will (recursively) be searched for doctests.\r
-\r
- The globals for each DocTest is formed by combining `globs`\r
- and `extraglobs` (bindings in `extraglobs` override bindings\r
- in `globs`). A new copy of the globals dictionary is created\r
- for each DocTest. If `globs` is not specified, then it\r
- defaults to the module's `__dict__`, if specified, or {}\r
- otherwise. If `extraglobs` is not specified, then it defaults\r
- to {}.\r
-\r
- """\r
- # If name was not specified, then extract it from the object.\r
- if name is None:\r
- name = getattr(obj, '__name__', None)\r
- if name is None:\r
- raise ValueError("DocTestFinder.find: name must be given "\r
- "when obj.__name__ doesn't exist: %r" %\r
- (type(obj),))\r
-\r
- # Find the module that contains the given object (if obj is\r
- # a module, then module=obj.). Note: this may fail, in which\r
- # case module will be None.\r
- if module is False:\r
- module = None\r
- elif module is None:\r
- module = inspect.getmodule(obj)\r
-\r
- # Read the module's source code. This is used by\r
- # DocTestFinder._find_lineno to find the line number for a\r
- # given object's docstring.\r
- try:\r
- file = inspect.getsourcefile(obj) or inspect.getfile(obj)\r
- if module is not None:\r
- # Supply the module globals in case the module was\r
- # originally loaded via a PEP 302 loader and\r
- # file is not a valid filesystem path\r
- source_lines = linecache.getlines(file, module.__dict__)\r
- else:\r
- # No access to a loader, so assume it's a normal\r
- # filesystem path\r
- source_lines = linecache.getlines(file)\r
- if not source_lines:\r
- source_lines = None\r
- except TypeError:\r
- source_lines = None\r
-\r
- # Initialize globals, and merge in extraglobs.\r
- if globs is None:\r
- if module is None:\r
- globs = {}\r
- else:\r
- globs = module.__dict__.copy()\r
- else:\r
- globs = globs.copy()\r
- if extraglobs is not None:\r
- globs.update(extraglobs)\r
- if '__name__' not in globs:\r
- globs['__name__'] = '__main__' # provide a default module name\r
-\r
- # Recursively expore `obj`, extracting DocTests.\r
- tests = []\r
- self._find(tests, obj, name, module, source_lines, globs, {})\r
- # Sort the tests by alpha order of names, for consistency in\r
- # verbose-mode output. This was a feature of doctest in Pythons\r
- # <= 2.3 that got lost by accident in 2.4. It was repaired in\r
- # 2.4.4 and 2.5.\r
- tests.sort()\r
- return tests\r
-\r
- def _from_module(self, module, object):\r
- """\r
- Return true if the given object is defined in the given\r
- module.\r
- """\r
- if module is None:\r
- return True\r
- elif inspect.getmodule(object) is not None:\r
- return module is inspect.getmodule(object)\r
- elif inspect.isfunction(object):\r
- return module.__dict__ is object.func_globals\r
- elif inspect.isclass(object):\r
- return module.__name__ == object.__module__\r
- elif hasattr(object, '__module__'):\r
- return module.__name__ == object.__module__\r
- elif isinstance(object, property):\r
- return True # [XX] no way not be sure.\r
- else:\r
- raise ValueError("object must be a class or function")\r
-\r
- def _find(self, tests, obj, name, module, source_lines, globs, seen):\r
- """\r
- Find tests for the given object and any contained objects, and\r
- add them to `tests`.\r
- """\r
- if self._verbose:\r
- print 'Finding tests in %s' % name\r
-\r
- # If we've already processed this object, then ignore it.\r
- if id(obj) in seen:\r
- return\r
- seen[id(obj)] = 1\r
-\r
- # Find a test for this object, and add it to the list of tests.\r
- test = self._get_test(obj, name, module, globs, source_lines)\r
- if test is not None:\r
- tests.append(test)\r
-\r
- # Look for tests in a module's contained objects.\r
- if inspect.ismodule(obj) and self._recurse:\r
- for valname, val in obj.__dict__.items():\r
- valname = '%s.%s' % (name, valname)\r
- # Recurse to functions & classes.\r
- if ((inspect.isfunction(val) or inspect.isclass(val)) and\r
- self._from_module(module, val)):\r
- self._find(tests, val, valname, module, source_lines,\r
- globs, seen)\r
-\r
- # Look for tests in a module's __test__ dictionary.\r
- if inspect.ismodule(obj) and self._recurse:\r
- for valname, val in getattr(obj, '__test__', {}).items():\r
- if not isinstance(valname, basestring):\r
- raise ValueError("DocTestFinder.find: __test__ keys "\r
- "must be strings: %r" %\r
- (type(valname),))\r
- if not (inspect.isfunction(val) or inspect.isclass(val) or\r
- inspect.ismethod(val) or inspect.ismodule(val) or\r
- isinstance(val, basestring)):\r
- raise ValueError("DocTestFinder.find: __test__ values "\r
- "must be strings, functions, methods, "\r
- "classes, or modules: %r" %\r
- (type(val),))\r
- valname = '%s.__test__.%s' % (name, valname)\r
- self._find(tests, val, valname, module, source_lines,\r
- globs, seen)\r
-\r
- # Look for tests in a class's contained objects.\r
- if inspect.isclass(obj) and self._recurse:\r
- for valname, val in obj.__dict__.items():\r
- # Special handling for staticmethod/classmethod.\r
- if isinstance(val, staticmethod):\r
- val = getattr(obj, valname)\r
- if isinstance(val, classmethod):\r
- val = getattr(obj, valname).im_func\r
-\r
- # Recurse to methods, properties, and nested classes.\r
- if ((inspect.isfunction(val) or inspect.isclass(val) or\r
- isinstance(val, property)) and\r
- self._from_module(module, val)):\r
- valname = '%s.%s' % (name, valname)\r
- self._find(tests, val, valname, module, source_lines,\r
- globs, seen)\r
-\r
- def _get_test(self, obj, name, module, globs, source_lines):\r
- """\r
- Return a DocTest for the given object, if it defines a docstring;\r
- otherwise, return None.\r
- """\r
- # Extract the object's docstring. If it doesn't have one,\r
- # then return None (no test for this object).\r
- if isinstance(obj, basestring):\r
- docstring = obj\r
- else:\r
- try:\r
- if obj.__doc__ is None:\r
- docstring = ''\r
- else:\r
- docstring = obj.__doc__\r
- if not isinstance(docstring, basestring):\r
- docstring = str(docstring)\r
- except (TypeError, AttributeError):\r
- docstring = ''\r
-\r
- # Find the docstring's location in the file.\r
- lineno = self._find_lineno(obj, source_lines)\r
-\r
- # Don't bother if the docstring is empty.\r
- if self._exclude_empty and not docstring:\r
- return None\r
-\r
- # Return a DocTest for this object.\r
- if module is None:\r
- filename = None\r
- else:\r
- filename = getattr(module, '__file__', module.__name__)\r
- if filename[-4:] in (".pyc", ".pyo"):\r
- filename = filename[:-1]\r
- return self._parser.get_doctest(docstring, globs, name,\r
- filename, lineno)\r
-\r
- def _find_lineno(self, obj, source_lines):\r
- """\r
- Return a line number of the given object's docstring. Note:\r
- this method assumes that the object has a docstring.\r
- """\r
- lineno = None\r
-\r
- # Find the line number for modules.\r
- if inspect.ismodule(obj):\r
- lineno = 0\r
-\r
- # Find the line number for classes.\r
- # Note: this could be fooled if a class is defined multiple\r
- # times in a single file.\r
- if inspect.isclass(obj):\r
- if source_lines is None:\r
- return None\r
- pat = re.compile(r'^\s*class\s*%s\b' %\r
- getattr(obj, '__name__', '-'))\r
- for i, line in enumerate(source_lines):\r
- if pat.match(line):\r
- lineno = i\r
- break\r
-\r
- # Find the line number for functions & methods.\r
- if inspect.ismethod(obj): obj = obj.im_func\r
- if inspect.isfunction(obj): obj = obj.func_code\r
- if inspect.istraceback(obj): obj = obj.tb_frame\r
- if inspect.isframe(obj): obj = obj.f_code\r
- if inspect.iscode(obj):\r
- lineno = getattr(obj, 'co_firstlineno', None)-1\r
-\r
- # Find the line number where the docstring starts. Assume\r
- # that it's the first line that begins with a quote mark.\r
- # Note: this could be fooled by a multiline function\r
- # signature, where a continuation line begins with a quote\r
- # mark.\r
- if lineno is not None:\r
- if source_lines is None:\r
- return lineno+1\r
- pat = re.compile('(^|.*:)\s*\w*("|\')')\r
- for lineno in range(lineno, len(source_lines)):\r
- if pat.match(source_lines[lineno]):\r
- return lineno\r
-\r
- # We couldn't find the line number.\r
- return None\r
-\r
-######################################################################\r
-## 5. DocTest Runner\r
-######################################################################\r
-\r
-class DocTestRunner:\r
- """\r
- A class used to run DocTest test cases, and accumulate statistics.\r
- The `run` method is used to process a single DocTest case. It\r
- returns a tuple `(f, t)`, where `t` is the number of test cases\r
- tried, and `f` is the number of test cases that failed.\r
-\r
- >>> tests = DocTestFinder().find(_TestClass)\r
- >>> runner = DocTestRunner(verbose=False)\r
- >>> tests.sort(key = lambda test: test.name)\r
- >>> for test in tests:\r
- ... print test.name, '->', runner.run(test)\r
- _TestClass -> TestResults(failed=0, attempted=2)\r
- _TestClass.__init__ -> TestResults(failed=0, attempted=2)\r
- _TestClass.get -> TestResults(failed=0, attempted=2)\r
- _TestClass.square -> TestResults(failed=0, attempted=1)\r
-\r
- The `summarize` method prints a summary of all the test cases that\r
- have been run by the runner, and returns an aggregated `(f, t)`\r
- tuple:\r
-\r
- >>> runner.summarize(verbose=1)\r
- 4 items passed all tests:\r
- 2 tests in _TestClass\r
- 2 tests in _TestClass.__init__\r
- 2 tests in _TestClass.get\r
- 1 tests in _TestClass.square\r
- 7 tests in 4 items.\r
- 7 passed and 0 failed.\r
- Test passed.\r
- TestResults(failed=0, attempted=7)\r
-\r
- The aggregated number of tried examples and failed examples is\r
- also available via the `tries` and `failures` attributes:\r
-\r
- >>> runner.tries\r
- 7\r
- >>> runner.failures\r
- 0\r
-\r
- The comparison between expected outputs and actual outputs is done\r
- by an `OutputChecker`. This comparison may be customized with a\r
- number of option flags; see the documentation for `testmod` for\r
- more information. If the option flags are insufficient, then the\r
- comparison may also be customized by passing a subclass of\r
- `OutputChecker` to the constructor.\r
-\r
- The test runner's display output can be controlled in two ways.\r
- First, an output function (`out) can be passed to\r
- `TestRunner.run`; this function will be called with strings that\r
- should be displayed. It defaults to `sys.stdout.write`. If\r
- capturing the output is not sufficient, then the display output\r
- can be also customized by subclassing DocTestRunner, and\r
- overriding the methods `report_start`, `report_success`,\r
- `report_unexpected_exception`, and `report_failure`.\r
- """\r
- # This divider string is used to separate failure messages, and to\r
- # separate sections of the summary.\r
- DIVIDER = "*" * 70\r
-\r
- def __init__(self, checker=None, verbose=None, optionflags=0):\r
- """\r
- Create a new test runner.\r
-\r
- Optional keyword arg `checker` is the `OutputChecker` that\r
- should be used to compare the expected outputs and actual\r
- outputs of doctest examples.\r
-\r
- Optional keyword arg 'verbose' prints lots of stuff if true,\r
- only failures if false; by default, it's true iff '-v' is in\r
- sys.argv.\r
-\r
- Optional argument `optionflags` can be used to control how the\r
- test runner compares expected output to actual output, and how\r
- it displays failures. See the documentation for `testmod` for\r
- more information.\r
- """\r
- self._checker = checker or OutputChecker()\r
- if verbose is None:\r
- verbose = '-v' in sys.argv\r
- self._verbose = verbose\r
- self.optionflags = optionflags\r
- self.original_optionflags = optionflags\r
-\r
- # Keep track of the examples we've run.\r
- self.tries = 0\r
- self.failures = 0\r
- self._name2ft = {}\r
-\r
- # Create a fake output target for capturing doctest output.\r
- self._fakeout = _SpoofOut()\r
-\r
- #/////////////////////////////////////////////////////////////////\r
- # Reporting methods\r
- #/////////////////////////////////////////////////////////////////\r
-\r
- def report_start(self, out, test, example):\r
- """\r
- Report that the test runner is about to process the given\r
- example. (Only displays a message if verbose=True)\r
- """\r
- if self._verbose:\r
- if example.want:\r
- out('Trying:\n' + _indent(example.source) +\r
- 'Expecting:\n' + _indent(example.want))\r
- else:\r
- out('Trying:\n' + _indent(example.source) +\r
- 'Expecting nothing\n')\r
-\r
- def report_success(self, out, test, example, got):\r
- """\r
- Report that the given example ran successfully. (Only\r
- displays a message if verbose=True)\r
- """\r
- if self._verbose:\r
- out("ok\n")\r
-\r
- def report_failure(self, out, test, example, got):\r
- """\r
- Report that the given example failed.\r
- """\r
- out(self._failure_header(test, example) +\r
- self._checker.output_difference(example, got, self.optionflags))\r
-\r
- def report_unexpected_exception(self, out, test, example, exc_info):\r
- """\r
- Report that the given example raised an unexpected exception.\r
- """\r
- out(self._failure_header(test, example) +\r
- 'Exception raised:\n' + _indent(_exception_traceback(exc_info)))\r
-\r
- def _failure_header(self, test, example):\r
- out = [self.DIVIDER]\r
- if test.filename:\r
- if test.lineno is not None and example.lineno is not None:\r
- lineno = test.lineno + example.lineno + 1\r
- else:\r
- lineno = '?'\r
- out.append('File "%s", line %s, in %s' %\r
- (test.filename, lineno, test.name))\r
- else:\r
- out.append('Line %s, in %s' % (example.lineno+1, test.name))\r
- out.append('Failed example:')\r
- source = example.source\r
- out.append(_indent(source))\r
- return '\n'.join(out)\r
-\r
- #/////////////////////////////////////////////////////////////////\r
- # DocTest Running\r
- #/////////////////////////////////////////////////////////////////\r
-\r
- def __run(self, test, compileflags, out):\r
- """\r
- Run the examples in `test`. Write the outcome of each example\r
- with one of the `DocTestRunner.report_*` methods, using the\r
- writer function `out`. `compileflags` is the set of compiler\r
- flags that should be used to execute examples. Return a tuple\r
- `(f, t)`, where `t` is the number of examples tried, and `f`\r
- is the number of examples that failed. The examples are run\r
- in the namespace `test.globs`.\r
- """\r
- # Keep track of the number of failures and tries.\r
- failures = tries = 0\r
-\r
- # Save the option flags (since option directives can be used\r
- # to modify them).\r
- original_optionflags = self.optionflags\r
-\r
- SUCCESS, FAILURE, BOOM = range(3) # `outcome` state\r
-\r
- check = self._checker.check_output\r
-\r
- # Process each example.\r
- for examplenum, example in enumerate(test.examples):\r
-\r
- # If REPORT_ONLY_FIRST_FAILURE is set, then suppress\r
- # reporting after the first failure.\r
- quiet = (self.optionflags & REPORT_ONLY_FIRST_FAILURE and\r
- failures > 0)\r
-\r
- # Merge in the example's options.\r
- self.optionflags = original_optionflags\r
- if example.options:\r
- for (optionflag, val) in example.options.items():\r
- if val:\r
- self.optionflags |= optionflag\r
- else:\r
- self.optionflags &= ~optionflag\r
-\r
- # If 'SKIP' is set, then skip this example.\r
- if self.optionflags & SKIP:\r
- continue\r
-\r
- # Record that we started this example.\r
- tries += 1\r
- if not quiet:\r
- self.report_start(out, test, example)\r
-\r
- # Use a special filename for compile(), so we can retrieve\r
- # the source code during interactive debugging (see\r
- # __patched_linecache_getlines).\r
- filename = '<doctest %s[%d]>' % (test.name, examplenum)\r
-\r
- # Run the example in the given context (globs), and record\r
- # any exception that gets raised. (But don't intercept\r
- # keyboard interrupts.)\r
- try:\r
- # Don't blink! This is where the user's code gets run.\r
- exec compile(example.source, filename, "single",\r
- compileflags, 1) in test.globs\r
- self.debugger.set_continue() # ==== Example Finished ====\r
- exception = None\r
- except KeyboardInterrupt:\r
- raise\r
- except:\r
- exception = sys.exc_info()\r
- self.debugger.set_continue() # ==== Example Finished ====\r
-\r
- got = self._fakeout.getvalue() # the actual output\r
- self._fakeout.truncate(0)\r
- outcome = FAILURE # guilty until proved innocent or insane\r
-\r
- # If the example executed without raising any exceptions,\r
- # verify its output.\r
- if exception is None:\r
- if check(example.want, got, self.optionflags):\r
- outcome = SUCCESS\r
-\r
- # The example raised an exception: check if it was expected.\r
- else:\r
- exc_info = sys.exc_info()\r
- exc_msg = traceback.format_exception_only(*exc_info[:2])[-1]\r
- if not quiet:\r
- got += _exception_traceback(exc_info)\r
-\r
- # If `example.exc_msg` is None, then we weren't expecting\r
- # an exception.\r
- if example.exc_msg is None:\r
- outcome = BOOM\r
-\r
- # We expected an exception: see whether it matches.\r
- elif check(example.exc_msg, exc_msg, self.optionflags):\r
- outcome = SUCCESS\r
-\r
- # Another chance if they didn't care about the detail.\r
- elif self.optionflags & IGNORE_EXCEPTION_DETAIL:\r
- m1 = re.match(r'(?:[^:]*\.)?([^:]*:)', example.exc_msg)\r
- m2 = re.match(r'(?:[^:]*\.)?([^:]*:)', exc_msg)\r
- if m1 and m2 and check(m1.group(1), m2.group(1),\r
- self.optionflags):\r
- outcome = SUCCESS\r
-\r
- # Report the outcome.\r
- if outcome is SUCCESS:\r
- if not quiet:\r
- self.report_success(out, test, example, got)\r
- elif outcome is FAILURE:\r
- if not quiet:\r
- self.report_failure(out, test, example, got)\r
- failures += 1\r
- elif outcome is BOOM:\r
- if not quiet:\r
- self.report_unexpected_exception(out, test, example,\r
- exc_info)\r
- failures += 1\r
- else:\r
- assert False, ("unknown outcome", outcome)\r
-\r
- # Restore the option flags (in case they were modified)\r
- self.optionflags = original_optionflags\r
-\r
- # Record and return the number of failures and tries.\r
- self.__record_outcome(test, failures, tries)\r
- return TestResults(failures, tries)\r
-\r
- def __record_outcome(self, test, f, t):\r
- """\r
- Record the fact that the given DocTest (`test`) generated `f`\r
- failures out of `t` tried examples.\r
- """\r
- f2, t2 = self._name2ft.get(test.name, (0,0))\r
- self._name2ft[test.name] = (f+f2, t+t2)\r
- self.failures += f\r
- self.tries += t\r
-\r
- __LINECACHE_FILENAME_RE = re.compile(r'<doctest '\r
- r'(?P<name>.+)'\r
- r'\[(?P<examplenum>\d+)\]>$')\r
- def __patched_linecache_getlines(self, filename, module_globals=None):\r
- m = self.__LINECACHE_FILENAME_RE.match(filename)\r
- if m and m.group('name') == self.test.name:\r
- example = self.test.examples[int(m.group('examplenum'))]\r
- source = example.source\r
- if isinstance(source, unicode):\r
- source = source.encode('ascii', 'backslashreplace')\r
- return source.splitlines(True)\r
- else:\r
- return self.save_linecache_getlines(filename, module_globals)\r
-\r
- def run(self, test, compileflags=None, out=None, clear_globs=True):\r
- """\r
- Run the examples in `test`, and display the results using the\r
- writer function `out`.\r
-\r
- The examples are run in the namespace `test.globs`. If\r
- `clear_globs` is true (the default), then this namespace will\r
- be cleared after the test runs, to help with garbage\r
- collection. If you would like to examine the namespace after\r
- the test completes, then use `clear_globs=False`.\r
-\r
- `compileflags` gives the set of flags that should be used by\r
- the Python compiler when running the examples. If not\r
- specified, then it will default to the set of future-import\r
- flags that apply to `globs`.\r
-\r
- The output of each example is checked using\r
- `DocTestRunner.check_output`, and the results are formatted by\r
- the `DocTestRunner.report_*` methods.\r
- """\r
- self.test = test\r
-\r
- if compileflags is None:\r
- compileflags = _extract_future_flags(test.globs)\r
-\r
- save_stdout = sys.stdout\r
- if out is None:\r
- out = save_stdout.write\r
- sys.stdout = self._fakeout\r
-\r
- # Patch pdb.set_trace to restore sys.stdout during interactive\r
- # debugging (so it's not still redirected to self._fakeout).\r
- # Note that the interactive output will go to *our*\r
- # save_stdout, even if that's not the real sys.stdout; this\r
- # allows us to write test cases for the set_trace behavior.\r
- save_set_trace = pdb.set_trace\r
- self.debugger = _OutputRedirectingPdb(save_stdout)\r
- self.debugger.reset()\r
- pdb.set_trace = self.debugger.set_trace\r
-\r
- # Patch linecache.getlines, so we can see the example's source\r
- # when we're inside the debugger.\r
- self.save_linecache_getlines = linecache.getlines\r
- linecache.getlines = self.__patched_linecache_getlines\r
-\r
- # Make sure sys.displayhook just prints the value to stdout\r
- save_displayhook = sys.displayhook\r
- sys.displayhook = sys.__displayhook__\r
-\r
- try:\r
- return self.__run(test, compileflags, out)\r
- finally:\r
- sys.stdout = save_stdout\r
- pdb.set_trace = save_set_trace\r
- linecache.getlines = self.save_linecache_getlines\r
- sys.displayhook = save_displayhook\r
- if clear_globs:\r
- test.globs.clear()\r
-\r
- #/////////////////////////////////////////////////////////////////\r
- # Summarization\r
- #/////////////////////////////////////////////////////////////////\r
- def summarize(self, verbose=None):\r
- """\r
- Print a summary of all the test cases that have been run by\r
- this DocTestRunner, and return a tuple `(f, t)`, where `f` is\r
- the total number of failed examples, and `t` is the total\r
- number of tried examples.\r
-\r
- The optional `verbose` argument controls how detailed the\r
- summary is. If the verbosity is not specified, then the\r
- DocTestRunner's verbosity is used.\r
- """\r
- if verbose is None:\r
- verbose = self._verbose\r
- notests = []\r
- passed = []\r
- failed = []\r
- totalt = totalf = 0\r
- for x in self._name2ft.items():\r
- name, (f, t) = x\r
- assert f <= t\r
- totalt += t\r
- totalf += f\r
- if t == 0:\r
- notests.append(name)\r
- elif f == 0:\r
- passed.append( (name, t) )\r
- else:\r
- failed.append(x)\r
- if verbose:\r
- if notests:\r
- print len(notests), "items had no tests:"\r
- notests.sort()\r
- for thing in notests:\r
- print " ", thing\r
- if passed:\r
- print len(passed), "items passed all tests:"\r
- passed.sort()\r
- for thing, count in passed:\r
- print " %3d tests in %s" % (count, thing)\r
- if failed:\r
- print self.DIVIDER\r
- print len(failed), "items had failures:"\r
- failed.sort()\r
- for thing, (f, t) in failed:\r
- print " %3d of %3d in %s" % (f, t, thing)\r
- if verbose:\r
- print totalt, "tests in", len(self._name2ft), "items."\r
- print totalt - totalf, "passed and", totalf, "failed."\r
- if totalf:\r
- print "***Test Failed***", totalf, "failures."\r
- elif verbose:\r
- print "Test passed."\r
- return TestResults(totalf, totalt)\r
-\r
- #/////////////////////////////////////////////////////////////////\r
- # Backward compatibility cruft to maintain doctest.master.\r
- #/////////////////////////////////////////////////////////////////\r
- def merge(self, other):\r
- d = self._name2ft\r
- for name, (f, t) in other._name2ft.items():\r
- if name in d:\r
- # Don't print here by default, since doing\r
- # so breaks some of the buildbots\r
- #print "*** DocTestRunner.merge: '" + name + "' in both" \\r
- # " testers; summing outcomes."\r
- f2, t2 = d[name]\r
- f = f + f2\r
- t = t + t2\r
- d[name] = f, t\r
-\r
-class OutputChecker:\r
- """\r
- A class used to check the whether the actual output from a doctest\r
- example matches the expected output. `OutputChecker` defines two\r
- methods: `check_output`, which compares a given pair of outputs,\r
- and returns true if they match; and `output_difference`, which\r
- returns a string describing the differences between two outputs.\r
- """\r
- def check_output(self, want, got, optionflags):\r
- """\r
- Return True iff the actual output from an example (`got`)\r
- matches the expected output (`want`). These strings are\r
- always considered to match if they are identical; but\r
- depending on what option flags the test runner is using,\r
- several non-exact match types are also possible. See the\r
- documentation for `TestRunner` for more information about\r
- option flags.\r
- """\r
- # Handle the common case first, for efficiency:\r
- # if they're string-identical, always return true.\r
- if got == want:\r
- return True\r
-\r
- # The values True and False replaced 1 and 0 as the return\r
- # value for boolean comparisons in Python 2.3.\r
- if not (optionflags & DONT_ACCEPT_TRUE_FOR_1):\r
- if (got,want) == ("True\n", "1\n"):\r
- return True\r
- if (got,want) == ("False\n", "0\n"):\r
- return True\r
-\r
- # <BLANKLINE> can be used as a special sequence to signify a\r
- # blank line, unless the DONT_ACCEPT_BLANKLINE flag is used.\r
- if not (optionflags & DONT_ACCEPT_BLANKLINE):\r
- # Replace <BLANKLINE> in want with a blank line.\r
- want = re.sub('(?m)^%s\s*?$' % re.escape(BLANKLINE_MARKER),\r
- '', want)\r
- # If a line in got contains only spaces, then remove the\r
- # spaces.\r
- got = re.sub('(?m)^\s*?$', '', got)\r
- if got == want:\r
- return True\r
-\r
- # This flag causes doctest to ignore any differences in the\r
- # contents of whitespace strings. Note that this can be used\r
- # in conjunction with the ELLIPSIS flag.\r
- if optionflags & NORMALIZE_WHITESPACE:\r
- got = ' '.join(got.split())\r
- want = ' '.join(want.split())\r
- if got == want:\r
- return True\r
-\r
- # The ELLIPSIS flag says to let the sequence "..." in `want`\r
- # match any substring in `got`.\r
- if optionflags & ELLIPSIS:\r
- if _ellipsis_match(want, got):\r
- return True\r
-\r
- # We didn't find any match; return false.\r
- return False\r
-\r
- # Should we do a fancy diff?\r
- def _do_a_fancy_diff(self, want, got, optionflags):\r
- # Not unless they asked for a fancy diff.\r
- if not optionflags & (REPORT_UDIFF |\r
- REPORT_CDIFF |\r
- REPORT_NDIFF):\r
- return False\r
-\r
- # If expected output uses ellipsis, a meaningful fancy diff is\r
- # too hard ... or maybe not. In two real-life failures Tim saw,\r
- # a diff was a major help anyway, so this is commented out.\r
- # [todo] _ellipsis_match() knows which pieces do and don't match,\r
- # and could be the basis for a kick-ass diff in this case.\r
- ##if optionflags & ELLIPSIS and ELLIPSIS_MARKER in want:\r
- ## return False\r
-\r
- # ndiff does intraline difference marking, so can be useful even\r
- # for 1-line differences.\r
- if optionflags & REPORT_NDIFF:\r
- return True\r
-\r
- # The other diff types need at least a few lines to be helpful.\r
- return want.count('\n') > 2 and got.count('\n') > 2\r
-\r
- def output_difference(self, example, got, optionflags):\r
- """\r
- Return a string describing the differences between the\r
- expected output for a given example (`example`) and the actual\r
- output (`got`). `optionflags` is the set of option flags used\r
- to compare `want` and `got`.\r
- """\r
- want = example.want\r
- # If <BLANKLINE>s are being used, then replace blank lines\r
- # with <BLANKLINE> in the actual output string.\r
- if not (optionflags & DONT_ACCEPT_BLANKLINE):\r
- got = re.sub('(?m)^[ ]*(?=\n)', BLANKLINE_MARKER, got)\r
-\r
- # Check if we should use diff.\r
- if self._do_a_fancy_diff(want, got, optionflags):\r
- # Split want & got into lines.\r
- want_lines = want.splitlines(True) # True == keep line ends\r
- got_lines = got.splitlines(True)\r
- # Use difflib to find their differences.\r
- if optionflags & REPORT_UDIFF:\r
- diff = difflib.unified_diff(want_lines, got_lines, n=2)\r
- diff = list(diff)[2:] # strip the diff header\r
- kind = 'unified diff with -expected +actual'\r
- elif optionflags & REPORT_CDIFF:\r
- diff = difflib.context_diff(want_lines, got_lines, n=2)\r
- diff = list(diff)[2:] # strip the diff header\r
- kind = 'context diff with expected followed by actual'\r
- elif optionflags & REPORT_NDIFF:\r
- engine = difflib.Differ(charjunk=difflib.IS_CHARACTER_JUNK)\r
- diff = list(engine.compare(want_lines, got_lines))\r
- kind = 'ndiff with -expected +actual'\r
- else:\r
- assert 0, 'Bad diff option'\r
- # Remove trailing whitespace on diff output.\r
- diff = [line.rstrip() + '\n' for line in diff]\r
- return 'Differences (%s):\n' % kind + _indent(''.join(diff))\r
-\r
- # If we're not using diff, then simply list the expected\r
- # output followed by the actual output.\r
- if want and got:\r
- return 'Expected:\n%sGot:\n%s' % (_indent(want), _indent(got))\r
- elif want:\r
- return 'Expected:\n%sGot nothing\n' % _indent(want)\r
- elif got:\r
- return 'Expected nothing\nGot:\n%s' % _indent(got)\r
- else:\r
- return 'Expected nothing\nGot nothing\n'\r
-\r
-class DocTestFailure(Exception):\r
- """A DocTest example has failed in debugging mode.\r
-\r
- The exception instance has variables:\r
-\r
- - test: the DocTest object being run\r
-\r
- - example: the Example object that failed\r
-\r
- - got: the actual output\r
- """\r
- def __init__(self, test, example, got):\r
- self.test = test\r
- self.example = example\r
- self.got = got\r
-\r
- def __str__(self):\r
- return str(self.test)\r
-\r
-class UnexpectedException(Exception):\r
- """A DocTest example has encountered an unexpected exception\r
-\r
- The exception instance has variables:\r
-\r
- - test: the DocTest object being run\r
-\r
- - example: the Example object that failed\r
-\r
- - exc_info: the exception info\r
- """\r
- def __init__(self, test, example, exc_info):\r
- self.test = test\r
- self.example = example\r
- self.exc_info = exc_info\r
-\r
- def __str__(self):\r
- return str(self.test)\r
-\r
-class DebugRunner(DocTestRunner):\r
- r"""Run doc tests but raise an exception as soon as there is a failure.\r
-\r
- If an unexpected exception occurs, an UnexpectedException is raised.\r
- It contains the test, the example, and the original exception:\r
-\r
- >>> runner = DebugRunner(verbose=False)\r
- >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',\r
- ... {}, 'foo', 'foo.py', 0)\r
- >>> try:\r
- ... runner.run(test)\r
- ... except UnexpectedException, failure:\r
- ... pass\r
-\r
- >>> failure.test is test\r
- True\r
-\r
- >>> failure.example.want\r
- '42\n'\r
-\r
- >>> exc_info = failure.exc_info\r
- >>> raise exc_info[0], exc_info[1], exc_info[2]\r
- Traceback (most recent call last):\r
- ...\r
- KeyError\r
-\r
- We wrap the original exception to give the calling application\r
- access to the test and example information.\r
-\r
- If the output doesn't match, then a DocTestFailure is raised:\r
-\r
- >>> test = DocTestParser().get_doctest('''\r
- ... >>> x = 1\r
- ... >>> x\r
- ... 2\r
- ... ''', {}, 'foo', 'foo.py', 0)\r
-\r
- >>> try:\r
- ... runner.run(test)\r
- ... except DocTestFailure, failure:\r
- ... pass\r
-\r
- DocTestFailure objects provide access to the test:\r
-\r
- >>> failure.test is test\r
- True\r
-\r
- As well as to the example:\r
-\r
- >>> failure.example.want\r
- '2\n'\r
-\r
- and the actual output:\r
-\r
- >>> failure.got\r
- '1\n'\r
-\r
- If a failure or error occurs, the globals are left intact:\r
-\r
- >>> del test.globs['__builtins__']\r
- >>> test.globs\r
- {'x': 1}\r
-\r
- >>> test = DocTestParser().get_doctest('''\r
- ... >>> x = 2\r
- ... >>> raise KeyError\r
- ... ''', {}, 'foo', 'foo.py', 0)\r
-\r
- >>> runner.run(test)\r
- Traceback (most recent call last):\r
- ...\r
- UnexpectedException: <DocTest foo from foo.py:0 (2 examples)>\r
-\r
- >>> del test.globs['__builtins__']\r
- >>> test.globs\r
- {'x': 2}\r
-\r
- But the globals are cleared if there is no error:\r
-\r
- >>> test = DocTestParser().get_doctest('''\r
- ... >>> x = 2\r
- ... ''', {}, 'foo', 'foo.py', 0)\r
-\r
- >>> runner.run(test)\r
- TestResults(failed=0, attempted=1)\r
-\r
- >>> test.globs\r
- {}\r
-\r
- """\r
-\r
- def run(self, test, compileflags=None, out=None, clear_globs=True):\r
- r = DocTestRunner.run(self, test, compileflags, out, False)\r
- if clear_globs:\r
- test.globs.clear()\r
- return r\r
-\r
- def report_unexpected_exception(self, out, test, example, exc_info):\r
- raise UnexpectedException(test, example, exc_info)\r
-\r
- def report_failure(self, out, test, example, got):\r
- raise DocTestFailure(test, example, got)\r
-\r
-######################################################################\r
-## 6. Test Functions\r
-######################################################################\r
-# These should be backwards compatible.\r
-\r
-# For backward compatibility, a global instance of a DocTestRunner\r
-# class, updated by testmod.\r
-master = None\r
-\r
-def testmod(m=None, name=None, globs=None, verbose=None,\r
- report=True, optionflags=0, extraglobs=None,\r
- raise_on_error=False, exclude_empty=False):\r
- """m=None, name=None, globs=None, verbose=None, report=True,\r
- optionflags=0, extraglobs=None, raise_on_error=False,\r
- exclude_empty=False\r
-\r
- Test examples in docstrings in functions and classes reachable\r
- from module m (or the current module if m is not supplied), starting\r
- with m.__doc__.\r
-\r
- Also test examples reachable from dict m.__test__ if it exists and is\r
- not None. m.__test__ maps names to functions, classes and strings;\r
- function and class docstrings are tested even if the name is private;\r
- strings are tested directly, as if they were docstrings.\r
-\r
- Return (#failures, #tests).\r
-\r
- See help(doctest) for an overview.\r
-\r
- Optional keyword arg "name" gives the name of the module; by default\r
- use m.__name__.\r
-\r
- Optional keyword arg "globs" gives a dict to be used as the globals\r
- when executing examples; by default, use m.__dict__. A copy of this\r
- dict is actually used for each docstring, so that each docstring's\r
- examples start with a clean slate.\r
-\r
- Optional keyword arg "extraglobs" gives a dictionary that should be\r
- merged into the globals that are used to execute examples. By\r
- default, no extra globals are used. This is new in 2.4.\r
-\r
- Optional keyword arg "verbose" prints lots of stuff if true, prints\r
- only failures if false; by default, it's true iff "-v" is in sys.argv.\r
-\r
- Optional keyword arg "report" prints a summary at the end when true,\r
- else prints nothing at the end. In verbose mode, the summary is\r
- detailed, else very brief (in fact, empty if all tests passed).\r
-\r
- Optional keyword arg "optionflags" or's together module constants,\r
- and defaults to 0. This is new in 2.3. Possible values (see the\r
- docs for details):\r
-\r
- DONT_ACCEPT_TRUE_FOR_1\r
- DONT_ACCEPT_BLANKLINE\r
- NORMALIZE_WHITESPACE\r
- ELLIPSIS\r
- SKIP\r
- IGNORE_EXCEPTION_DETAIL\r
- REPORT_UDIFF\r
- REPORT_CDIFF\r
- REPORT_NDIFF\r
- REPORT_ONLY_FIRST_FAILURE\r
-\r
- Optional keyword arg "raise_on_error" raises an exception on the\r
- first unexpected exception or failure. This allows failures to be\r
- post-mortem debugged.\r
-\r
- Advanced tomfoolery: testmod runs methods of a local instance of\r
- class doctest.Tester, then merges the results into (or creates)\r
- global Tester instance doctest.master. Methods of doctest.master\r
- can be called directly too, if you want to do something unusual.\r
- Passing report=0 to testmod is especially useful then, to delay\r
- displaying a summary. Invoke doctest.master.summarize(verbose)\r
- when you're done fiddling.\r
- """\r
- global master\r
-\r
- # If no module was given, then use __main__.\r
- if m is None:\r
- # DWA - m will still be None if this wasn't invoked from the command\r
- # line, in which case the following TypeError is about as good an error\r
- # as we should expect\r
- m = sys.modules.get('__main__')\r
-\r
- # Check that we were actually given a module.\r
- if not inspect.ismodule(m):\r
- raise TypeError("testmod: module required; %r" % (m,))\r
-\r
- # If no name was given, then use the module's name.\r
- if name is None:\r
- name = m.__name__\r
-\r
- # Find, parse, and run all tests in the given module.\r
- finder = DocTestFinder(exclude_empty=exclude_empty)\r
-\r
- if raise_on_error:\r
- runner = DebugRunner(verbose=verbose, optionflags=optionflags)\r
- else:\r
- runner = DocTestRunner(verbose=verbose, optionflags=optionflags)\r
-\r
- for test in finder.find(m, name, globs=globs, extraglobs=extraglobs):\r
- runner.run(test)\r
-\r
- if report:\r
- runner.summarize()\r
-\r
- if master is None:\r
- master = runner\r
- else:\r
- master.merge(runner)\r
-\r
- return TestResults(runner.failures, runner.tries)\r
-\r
-def testfile(filename, module_relative=True, name=None, package=None,\r
- globs=None, verbose=None, report=True, optionflags=0,\r
- extraglobs=None, raise_on_error=False, parser=DocTestParser(),\r
- encoding=None):\r
- """\r
- Test examples in the given file. Return (#failures, #tests).\r
-\r
- Optional keyword arg "module_relative" specifies how filenames\r
- should be interpreted:\r
-\r
- - If "module_relative" is True (the default), then "filename"\r
- specifies a module-relative path. By default, this path is\r
- relative to the calling module's directory; but if the\r
- "package" argument is specified, then it is relative to that\r
- package. To ensure os-independence, "filename" should use\r
- "/" characters to separate path segments, and should not\r
- be an absolute path (i.e., it may not begin with "/").\r
-\r
- - If "module_relative" is False, then "filename" specifies an\r
- os-specific path. The path may be absolute or relative (to\r
- the current working directory).\r
-\r
- Optional keyword arg "name" gives the name of the test; by default\r
- use the file's basename.\r
-\r
- Optional keyword argument "package" is a Python package or the\r
- name of a Python package whose directory should be used as the\r
- base directory for a module relative filename. If no package is\r
- specified, then the calling module's directory is used as the base\r
- directory for module relative filenames. It is an error to\r
- specify "package" if "module_relative" is False.\r
-\r
- Optional keyword arg "globs" gives a dict to be used as the globals\r
- when executing examples; by default, use {}. A copy of this dict\r
- is actually used for each docstring, so that each docstring's\r
- examples start with a clean slate.\r
-\r
- Optional keyword arg "extraglobs" gives a dictionary that should be\r
- merged into the globals that are used to execute examples. By\r
- default, no extra globals are used.\r
-\r
- Optional keyword arg "verbose" prints lots of stuff if true, prints\r
- only failures if false; by default, it's true iff "-v" is in sys.argv.\r
-\r
- Optional keyword arg "report" prints a summary at the end when true,\r
- else prints nothing at the end. In verbose mode, the summary is\r
- detailed, else very brief (in fact, empty if all tests passed).\r
-\r
- Optional keyword arg "optionflags" or's together module constants,\r
- and defaults to 0. Possible values (see the docs for details):\r
-\r
- DONT_ACCEPT_TRUE_FOR_1\r
- DONT_ACCEPT_BLANKLINE\r
- NORMALIZE_WHITESPACE\r
- ELLIPSIS\r
- SKIP\r
- IGNORE_EXCEPTION_DETAIL\r
- REPORT_UDIFF\r
- REPORT_CDIFF\r
- REPORT_NDIFF\r
- REPORT_ONLY_FIRST_FAILURE\r
-\r
- Optional keyword arg "raise_on_error" raises an exception on the\r
- first unexpected exception or failure. This allows failures to be\r
- post-mortem debugged.\r
-\r
- Optional keyword arg "parser" specifies a DocTestParser (or\r
- subclass) that should be used to extract tests from the files.\r
-\r
- Optional keyword arg "encoding" specifies an encoding that should\r
- be used to convert the file to unicode.\r
-\r
- Advanced tomfoolery: testmod runs methods of a local instance of\r
- class doctest.Tester, then merges the results into (or creates)\r
- global Tester instance doctest.master. Methods of doctest.master\r
- can be called directly too, if you want to do something unusual.\r
- Passing report=0 to testmod is especially useful then, to delay\r
- displaying a summary. Invoke doctest.master.summarize(verbose)\r
- when you're done fiddling.\r
- """\r
- global master\r
-\r
- if package and not module_relative:\r
- raise ValueError("Package may only be specified for module-"\r
- "relative paths.")\r
-\r
- # Relativize the path\r
- text, filename = _load_testfile(filename, package, module_relative)\r
-\r
- # If no name was given, then use the file's name.\r
- if name is None:\r
- name = os.path.basename(filename)\r
-\r
- # Assemble the globals.\r
- if globs is None:\r
- globs = {}\r
- else:\r
- globs = globs.copy()\r
- if extraglobs is not None:\r
- globs.update(extraglobs)\r
- if '__name__' not in globs:\r
- globs['__name__'] = '__main__'\r
-\r
- if raise_on_error:\r
- runner = DebugRunner(verbose=verbose, optionflags=optionflags)\r
- else:\r
- runner = DocTestRunner(verbose=verbose, optionflags=optionflags)\r
-\r
- if encoding is not None:\r
- text = text.decode(encoding)\r
-\r
- # Read the file, convert it to a test, and run it.\r
- test = parser.get_doctest(text, globs, name, filename, 0)\r
- runner.run(test)\r
-\r
- if report:\r
- runner.summarize()\r
-\r
- if master is None:\r
- master = runner\r
- else:\r
- master.merge(runner)\r
-\r
- return TestResults(runner.failures, runner.tries)\r
-\r
-def run_docstring_examples(f, globs, verbose=False, name="NoName",\r
- compileflags=None, optionflags=0):\r
- """\r
- Test examples in the given object's docstring (`f`), using `globs`\r
- as globals. Optional argument `name` is used in failure messages.\r
- If the optional argument `verbose` is true, then generate output\r
- even if there are no failures.\r
-\r
- `compileflags` gives the set of flags that should be used by the\r
- Python compiler when running the examples. If not specified, then\r
- it will default to the set of future-import flags that apply to\r
- `globs`.\r
-\r
- Optional keyword arg `optionflags` specifies options for the\r
- testing and output. See the documentation for `testmod` for more\r
- information.\r
- """\r
- # Find, parse, and run all tests in the given module.\r
- finder = DocTestFinder(verbose=verbose, recurse=False)\r
- runner = DocTestRunner(verbose=verbose, optionflags=optionflags)\r
- for test in finder.find(f, name, globs=globs):\r
- runner.run(test, compileflags=compileflags)\r
-\r
-######################################################################\r
-## 7. Tester\r
-######################################################################\r
-# This is provided only for backwards compatibility. It's not\r
-# actually used in any way.\r
-\r
-class Tester:\r
- def __init__(self, mod=None, globs=None, verbose=None, optionflags=0):\r
-\r
- warnings.warn("class Tester is deprecated; "\r
- "use class doctest.DocTestRunner instead",\r
- DeprecationWarning, stacklevel=2)\r
- if mod is None and globs is None:\r
- raise TypeError("Tester.__init__: must specify mod or globs")\r
- if mod is not None and not inspect.ismodule(mod):\r
- raise TypeError("Tester.__init__: mod must be a module; %r" %\r
- (mod,))\r
- if globs is None:\r
- globs = mod.__dict__\r
- self.globs = globs\r
-\r
- self.verbose = verbose\r
- self.optionflags = optionflags\r
- self.testfinder = DocTestFinder()\r
- self.testrunner = DocTestRunner(verbose=verbose,\r
- optionflags=optionflags)\r
-\r
- def runstring(self, s, name):\r
- test = DocTestParser().get_doctest(s, self.globs, name, None, None)\r
- if self.verbose:\r
- print "Running string", name\r
- (f,t) = self.testrunner.run(test)\r
- if self.verbose:\r
- print f, "of", t, "examples failed in string", name\r
- return TestResults(f,t)\r
-\r
- def rundoc(self, object, name=None, module=None):\r
- f = t = 0\r
- tests = self.testfinder.find(object, name, module=module,\r
- globs=self.globs)\r
- for test in tests:\r
- (f2, t2) = self.testrunner.run(test)\r
- (f,t) = (f+f2, t+t2)\r
- return TestResults(f,t)\r
-\r
- def rundict(self, d, name, module=None):\r
- import types\r
- m = types.ModuleType(name)\r
- m.__dict__.update(d)\r
- if module is None:\r
- module = False\r
- return self.rundoc(m, name, module)\r
-\r
- def run__test__(self, d, name):\r
- import types\r
- m = types.ModuleType(name)\r
- m.__test__ = d\r
- return self.rundoc(m, name)\r
-\r
- def summarize(self, verbose=None):\r
- return self.testrunner.summarize(verbose)\r
-\r
- def merge(self, other):\r
- self.testrunner.merge(other.testrunner)\r
-\r
-######################################################################\r
-## 8. Unittest Support\r
-######################################################################\r
-\r
-_unittest_reportflags = 0\r
-\r
-def set_unittest_reportflags(flags):\r
- """Sets the unittest option flags.\r
-\r
- The old flag is returned so that a runner could restore the old\r
- value if it wished to:\r
-\r
- >>> import doctest\r
- >>> old = doctest._unittest_reportflags\r
- >>> doctest.set_unittest_reportflags(REPORT_NDIFF |\r
- ... REPORT_ONLY_FIRST_FAILURE) == old\r
- True\r
-\r
- >>> doctest._unittest_reportflags == (REPORT_NDIFF |\r
- ... REPORT_ONLY_FIRST_FAILURE)\r
- True\r
-\r
- Only reporting flags can be set:\r
-\r
- >>> doctest.set_unittest_reportflags(ELLIPSIS)\r
- Traceback (most recent call last):\r
- ...\r
- ValueError: ('Only reporting flags allowed', 8)\r
-\r
- >>> doctest.set_unittest_reportflags(old) == (REPORT_NDIFF |\r
- ... REPORT_ONLY_FIRST_FAILURE)\r
- True\r
- """\r
- global _unittest_reportflags\r
-\r
- if (flags & REPORTING_FLAGS) != flags:\r
- raise ValueError("Only reporting flags allowed", flags)\r
- old = _unittest_reportflags\r
- _unittest_reportflags = flags\r
- return old\r
-\r
-\r
-class DocTestCase(unittest.TestCase):\r
-\r
- def __init__(self, test, optionflags=0, setUp=None, tearDown=None,\r
- checker=None):\r
-\r
- unittest.TestCase.__init__(self)\r
- self._dt_optionflags = optionflags\r
- self._dt_checker = checker\r
- self._dt_test = test\r
- self._dt_setUp = setUp\r
- self._dt_tearDown = tearDown\r
-\r
- def setUp(self):\r
- test = self._dt_test\r
-\r
- if self._dt_setUp is not None:\r
- self._dt_setUp(test)\r
-\r
- def tearDown(self):\r
- test = self._dt_test\r
-\r
- if self._dt_tearDown is not None:\r
- self._dt_tearDown(test)\r
-\r
- test.globs.clear()\r
-\r
- def runTest(self):\r
- test = self._dt_test\r
- old = sys.stdout\r
- new = StringIO()\r
- optionflags = self._dt_optionflags\r
-\r
- if not (optionflags & REPORTING_FLAGS):\r
- # The option flags don't include any reporting flags,\r
- # so add the default reporting flags\r
- optionflags |= _unittest_reportflags\r
-\r
- runner = DocTestRunner(optionflags=optionflags,\r
- checker=self._dt_checker, verbose=False)\r
-\r
- try:\r
- runner.DIVIDER = "-"*70\r
- failures, tries = runner.run(\r
- test, out=new.write, clear_globs=False)\r
- finally:\r
- sys.stdout = old\r
-\r
- if failures:\r
- raise self.failureException(self.format_failure(new.getvalue()))\r
-\r
- def format_failure(self, err):\r
- test = self._dt_test\r
- if test.lineno is None:\r
- lineno = 'unknown line number'\r
- else:\r
- lineno = '%s' % test.lineno\r
- lname = '.'.join(test.name.split('.')[-1:])\r
- return ('Failed doctest test for %s\n'\r
- ' File "%s", line %s, in %s\n\n%s'\r
- % (test.name, test.filename, lineno, lname, err)\r
- )\r
-\r
- def debug(self):\r
- r"""Run the test case without results and without catching exceptions\r
-\r
- The unit test framework includes a debug method on test cases\r
- and test suites to support post-mortem debugging. The test code\r
- is run in such a way that errors are not caught. This way a\r
- caller can catch the errors and initiate post-mortem debugging.\r
-\r
- The DocTestCase provides a debug method that raises\r
- UnexpectedException errors if there is an unexpected\r
- exception:\r
-\r
- >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',\r
- ... {}, 'foo', 'foo.py', 0)\r
- >>> case = DocTestCase(test)\r
- >>> try:\r
- ... case.debug()\r
- ... except UnexpectedException, failure:\r
- ... pass\r
-\r
- The UnexpectedException contains the test, the example, and\r
- the original exception:\r
-\r
- >>> failure.test is test\r
- True\r
-\r
- >>> failure.example.want\r
- '42\n'\r
-\r
- >>> exc_info = failure.exc_info\r
- >>> raise exc_info[0], exc_info[1], exc_info[2]\r
- Traceback (most recent call last):\r
- ...\r
- KeyError\r
-\r
- If the output doesn't match, then a DocTestFailure is raised:\r
-\r
- >>> test = DocTestParser().get_doctest('''\r
- ... >>> x = 1\r
- ... >>> x\r
- ... 2\r
- ... ''', {}, 'foo', 'foo.py', 0)\r
- >>> case = DocTestCase(test)\r
-\r
- >>> try:\r
- ... case.debug()\r
- ... except DocTestFailure, failure:\r
- ... pass\r
-\r
- DocTestFailure objects provide access to the test:\r
-\r
- >>> failure.test is test\r
- True\r
-\r
- As well as to the example:\r
-\r
- >>> failure.example.want\r
- '2\n'\r
-\r
- and the actual output:\r
-\r
- >>> failure.got\r
- '1\n'\r
-\r
- """\r
-\r
- self.setUp()\r
- runner = DebugRunner(optionflags=self._dt_optionflags,\r
- checker=self._dt_checker, verbose=False)\r
- runner.run(self._dt_test, clear_globs=False)\r
- self.tearDown()\r
-\r
- def id(self):\r
- return self._dt_test.name\r
-\r
- def __repr__(self):\r
- name = self._dt_test.name.split('.')\r
- return "%s (%s)" % (name[-1], '.'.join(name[:-1]))\r
-\r
- __str__ = __repr__\r
-\r
- def shortDescription(self):\r
- return "Doctest: " + self._dt_test.name\r
-\r
-class SkipDocTestCase(DocTestCase):\r
- def __init__(self):\r
- DocTestCase.__init__(self, None)\r
-\r
- def setUp(self):\r
- self.skipTest("DocTestSuite will not work with -O2 and above")\r
-\r
- def test_skip(self):\r
- pass\r
-\r
- def shortDescription(self):\r
- return "Skipping tests from %s" % module.__name__\r
-\r
-def DocTestSuite(module=None, globs=None, extraglobs=None, test_finder=None,\r
- **options):\r
- """\r
- Convert doctest tests for a module to a unittest test suite.\r
-\r
- This converts each documentation string in a module that\r
- contains doctest tests to a unittest test case. If any of the\r
- tests in a doc string fail, then the test case fails. An exception\r
- is raised showing the name of the file containing the test and a\r
- (sometimes approximate) line number.\r
-\r
- The `module` argument provides the module to be tested. The argument\r
- can be either a module or a module name.\r
-\r
- If no argument is given, the calling module is used.\r
-\r
- A number of options may be provided as keyword arguments:\r
-\r
- setUp\r
- A set-up function. This is called before running the\r
- tests in each file. The setUp function will be passed a DocTest\r
- object. The setUp function can access the test globals as the\r
- globs attribute of the test passed.\r
-\r
- tearDown\r
- A tear-down function. This is called after running the\r
- tests in each file. The tearDown function will be passed a DocTest\r
- object. The tearDown function can access the test globals as the\r
- globs attribute of the test passed.\r
-\r
- globs\r
- A dictionary containing initial global variables for the tests.\r
-\r
- optionflags\r
- A set of doctest option flags expressed as an integer.\r
- """\r
-\r
- if test_finder is None:\r
- test_finder = DocTestFinder()\r
-\r
- module = _normalize_module(module)\r
- tests = test_finder.find(module, globs=globs, extraglobs=extraglobs)\r
-\r
- if not tests and sys.flags.optimize >=2:\r
- # Skip doctests when running with -O2\r
- suite = unittest.TestSuite()\r
- suite.addTest(SkipDocTestCase())\r
- return suite\r
- elif not tests:\r
- # Why do we want to do this? Because it reveals a bug that might\r
- # otherwise be hidden.\r
- raise ValueError(module, "has no tests")\r
-\r
- tests.sort()\r
- suite = unittest.TestSuite()\r
-\r
- for test in tests:\r
- if len(test.examples) == 0:\r
- continue\r
- if not test.filename:\r
- filename = module.__file__\r
- if filename[-4:] in (".pyc", ".pyo"):\r
- filename = filename[:-1]\r
- test.filename = filename\r
- suite.addTest(DocTestCase(test, **options))\r
-\r
- return suite\r
-\r
-class DocFileCase(DocTestCase):\r
-\r
- def id(self):\r
- return '_'.join(self._dt_test.name.split('.'))\r
-\r
- def __repr__(self):\r
- return self._dt_test.filename\r
- __str__ = __repr__\r
-\r
- def format_failure(self, err):\r
- return ('Failed doctest test for %s\n File "%s", line 0\n\n%s'\r
- % (self._dt_test.name, self._dt_test.filename, err)\r
- )\r
-\r
-def DocFileTest(path, module_relative=True, package=None,\r
- globs=None, parser=DocTestParser(),\r
- encoding=None, **options):\r
- if globs is None:\r
- globs = {}\r
- else:\r
- globs = globs.copy()\r
-\r
- if package and not module_relative:\r
- raise ValueError("Package may only be specified for module-"\r
- "relative paths.")\r
-\r
- # Relativize the path.\r
- doc, path = _load_testfile(path, package, module_relative)\r
-\r
- if "__file__" not in globs:\r
- globs["__file__"] = path\r
-\r
- # Find the file and read it.\r
- name = os.path.basename(path)\r
-\r
- # If an encoding is specified, use it to convert the file to unicode\r
- if encoding is not None:\r
- doc = doc.decode(encoding)\r
-\r
- # Convert it to a test, and wrap it in a DocFileCase.\r
- test = parser.get_doctest(doc, globs, name, path, 0)\r
- return DocFileCase(test, **options)\r
-\r
-def DocFileSuite(*paths, **kw):\r
- """A unittest suite for one or more doctest files.\r
-\r
- The path to each doctest file is given as a string; the\r
- interpretation of that string depends on the keyword argument\r
- "module_relative".\r
-\r
- A number of options may be provided as keyword arguments:\r
-\r
- module_relative\r
- If "module_relative" is True, then the given file paths are\r
- interpreted as os-independent module-relative paths. By\r
- default, these paths are relative to the calling module's\r
- directory; but if the "package" argument is specified, then\r
- they are relative to that package. To ensure os-independence,\r
- "filename" should use "/" characters to separate path\r
- segments, and may not be an absolute path (i.e., it may not\r
- begin with "/").\r
-\r
- If "module_relative" is False, then the given file paths are\r
- interpreted as os-specific paths. These paths may be absolute\r
- or relative (to the current working directory).\r
-\r
- package\r
- A Python package or the name of a Python package whose directory\r
- should be used as the base directory for module relative paths.\r
- If "package" is not specified, then the calling module's\r
- directory is used as the base directory for module relative\r
- filenames. It is an error to specify "package" if\r
- "module_relative" is False.\r
-\r
- setUp\r
- A set-up function. This is called before running the\r
- tests in each file. The setUp function will be passed a DocTest\r
- object. The setUp function can access the test globals as the\r
- globs attribute of the test passed.\r
-\r
- tearDown\r
- A tear-down function. This is called after running the\r
- tests in each file. The tearDown function will be passed a DocTest\r
- object. The tearDown function can access the test globals as the\r
- globs attribute of the test passed.\r
-\r
- globs\r
- A dictionary containing initial global variables for the tests.\r
-\r
- optionflags\r
- A set of doctest option flags expressed as an integer.\r
-\r
- parser\r
- A DocTestParser (or subclass) that should be used to extract\r
- tests from the files.\r
-\r
- encoding\r
- An encoding that will be used to convert the files to unicode.\r
- """\r
- suite = unittest.TestSuite()\r
-\r
- # We do this here so that _normalize_module is called at the right\r
- # level. If it were called in DocFileTest, then this function\r
- # would be the caller and we might guess the package incorrectly.\r
- if kw.get('module_relative', True):\r
- kw['package'] = _normalize_module(kw.get('package'))\r
-\r
- for path in paths:\r
- suite.addTest(DocFileTest(path, **kw))\r
-\r
- return suite\r
-\r
-######################################################################\r
-## 9. Debugging Support\r
-######################################################################\r
-\r
-def script_from_examples(s):\r
- r"""Extract script from text with examples.\r
-\r
- Converts text with examples to a Python script. Example input is\r
- converted to regular code. Example output and all other words\r
- are converted to comments:\r
-\r
- >>> text = '''\r
- ... Here are examples of simple math.\r
- ...\r
- ... Python has super accurate integer addition\r
- ...\r
- ... >>> 2 + 2\r
- ... 5\r
- ...\r
- ... And very friendly error messages:\r
- ...\r
- ... >>> 1/0\r
- ... To Infinity\r
- ... And\r
- ... Beyond\r
- ...\r
- ... You can use logic if you want:\r
- ...\r
- ... >>> if 0:\r
- ... ... blah\r
- ... ... blah\r
- ... ...\r
- ...\r
- ... Ho hum\r
- ... '''\r
-\r
- >>> print script_from_examples(text)\r
- # Here are examples of simple math.\r
- #\r
- # Python has super accurate integer addition\r
- #\r
- 2 + 2\r
- # Expected:\r
- ## 5\r
- #\r
- # And very friendly error messages:\r
- #\r
- 1/0\r
- # Expected:\r
- ## To Infinity\r
- ## And\r
- ## Beyond\r
- #\r
- # You can use logic if you want:\r
- #\r
- if 0:\r
- blah\r
- blah\r
- #\r
- # Ho hum\r
- <BLANKLINE>\r
- """\r
- output = []\r
- for piece in DocTestParser().parse(s):\r
- if isinstance(piece, Example):\r
- # Add the example's source code (strip trailing NL)\r
- output.append(piece.source[:-1])\r
- # Add the expected output:\r
- want = piece.want\r
- if want:\r
- output.append('# Expected:')\r
- output += ['## '+l for l in want.split('\n')[:-1]]\r
- else:\r
- # Add non-example text.\r
- output += [_comment_line(l)\r
- for l in piece.split('\n')[:-1]]\r
-\r
- # Trim junk on both ends.\r
- while output and output[-1] == '#':\r
- output.pop()\r
- while output and output[0] == '#':\r
- output.pop(0)\r
- # Combine the output, and return it.\r
- # Add a courtesy newline to prevent exec from choking (see bug #1172785)\r
- return '\n'.join(output) + '\n'\r
-\r
-def testsource(module, name):\r
- """Extract the test sources from a doctest docstring as a script.\r
-\r
- Provide the module (or dotted name of the module) containing the\r
- test to be debugged and the name (within the module) of the object\r
- with the doc string with tests to be debugged.\r
- """\r
- module = _normalize_module(module)\r
- tests = DocTestFinder().find(module)\r
- test = [t for t in tests if t.name == name]\r
- if not test:\r
- raise ValueError(name, "not found in tests")\r
- test = test[0]\r
- testsrc = script_from_examples(test.docstring)\r
- return testsrc\r
-\r
-def debug_src(src, pm=False, globs=None):\r
- """Debug a single doctest docstring, in argument `src`'"""\r
- testsrc = script_from_examples(src)\r
- debug_script(testsrc, pm, globs)\r
-\r
-def debug_script(src, pm=False, globs=None):\r
- "Debug a test script. `src` is the script, as a string."\r
- import pdb\r
-\r
- # Note that tempfile.NameTemporaryFile() cannot be used. As the\r
- # docs say, a file so created cannot be opened by name a second time\r
- # on modern Windows boxes, and execfile() needs to open it.\r
- srcfilename = tempfile.mktemp(".py", "doctestdebug")\r
- f = open(srcfilename, 'w')\r
- f.write(src)\r
- f.close()\r
-\r
- try:\r
- if globs:\r
- globs = globs.copy()\r
- else:\r
- globs = {}\r
-\r
- if pm:\r
- try:\r
- execfile(srcfilename, globs, globs)\r
- except:\r
- print sys.exc_info()[1]\r
- pdb.post_mortem(sys.exc_info()[2])\r
- else:\r
- # Note that %r is vital here. '%s' instead can, e.g., cause\r
- # backslashes to get treated as metacharacters on Windows.\r
- pdb.run("execfile(%r)" % srcfilename, globs, globs)\r
-\r
- finally:\r
- os.remove(srcfilename)\r
-\r
-def debug(module, name, pm=False):\r
- """Debug a single doctest docstring.\r
-\r
- Provide the module (or dotted name of the module) containing the\r
- test to be debugged and the name (within the module) of the object\r
- with the docstring with tests to be debugged.\r
- """\r
- module = _normalize_module(module)\r
- testsrc = testsource(module, name)\r
- debug_script(testsrc, pm, module.__dict__)\r
-\r
-######################################################################\r
-## 10. Example Usage\r
-######################################################################\r
-class _TestClass:\r
- """\r
- A pointless class, for sanity-checking of docstring testing.\r
-\r
- Methods:\r
- square()\r
- get()\r
-\r
- >>> _TestClass(13).get() + _TestClass(-12).get()\r
- 1\r
- >>> hex(_TestClass(13).square().get())\r
- '0xa9'\r
- """\r
-\r
- def __init__(self, val):\r
- """val -> _TestClass object with associated value val.\r
-\r
- >>> t = _TestClass(123)\r
- >>> print t.get()\r
- 123\r
- """\r
-\r
- self.val = val\r
-\r
- def square(self):\r
- """square() -> square TestClass's associated value\r
-\r
- >>> _TestClass(13).square().get()\r
- 169\r
- """\r
-\r
- self.val = self.val ** 2\r
- return self\r
-\r
- def get(self):\r
- """get() -> return TestClass's associated value.\r
-\r
- >>> x = _TestClass(-42)\r
- >>> print x.get()\r
- -42\r
- """\r
-\r
- return self.val\r
-\r
-__test__ = {"_TestClass": _TestClass,\r
- "string": r"""\r
- Example of a string object, searched as-is.\r
- >>> x = 1; y = 2\r
- >>> x + y, x * y\r
- (3, 2)\r
- """,\r
-\r
- "bool-int equivalence": r"""\r
- In 2.2, boolean expressions displayed\r
- 0 or 1. By default, we still accept\r
- them. This can be disabled by passing\r
- DONT_ACCEPT_TRUE_FOR_1 to the new\r
- optionflags argument.\r
- >>> 4 == 4\r
- 1\r
- >>> 4 == 4\r
- True\r
- >>> 4 > 4\r
- 0\r
- >>> 4 > 4\r
- False\r
- """,\r
-\r
- "blank lines": r"""\r
- Blank lines can be marked with <BLANKLINE>:\r
- >>> print 'foo\n\nbar\n'\r
- foo\r
- <BLANKLINE>\r
- bar\r
- <BLANKLINE>\r
- """,\r
-\r
- "ellipsis": r"""\r
- If the ellipsis flag is used, then '...' can be used to\r
- elide substrings in the desired output:\r
- >>> print range(1000) #doctest: +ELLIPSIS\r
- [0, 1, 2, ..., 999]\r
- """,\r
-\r
- "whitespace normalization": r"""\r
- If the whitespace normalization flag is used, then\r
- differences in whitespace are ignored.\r
- >>> print range(30) #doctest: +NORMALIZE_WHITESPACE\r
- [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14,\r
- 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26,\r
- 27, 28, 29]\r
- """,\r
- }\r
-\r
-\r
-def _test():\r
- testfiles = [arg for arg in sys.argv[1:] if arg and arg[0] != '-']\r
- if not testfiles:\r
- name = os.path.basename(sys.argv[0])\r
- if '__loader__' in globals(): # python -m\r
- name, _ = os.path.splitext(name)\r
- print("usage: {0} [-v] file ...".format(name))\r
- return 2\r
- for filename in testfiles:\r
- if filename.endswith(".py"):\r
- # It is a module -- insert its dir into sys.path and try to\r
- # import it. If it is part of a package, that possibly\r
- # won't work because of package imports.\r
- dirname, filename = os.path.split(filename)\r
- sys.path.insert(0, dirname)\r
- m = __import__(filename[:-3])\r
- del sys.path[0]\r
- failures, _ = testmod(m)\r
- else:\r
- failures, _ = testfile(filename, module_relative=False)\r
- if failures:\r
- return 1\r
- return 0\r
-\r
-\r
-if __name__ == "__main__":\r
- sys.exit(_test())\r
projects / mirror_edk2.git / blobdiff