ipdoctest.py
762 lines
| 30.4 KiB
| text/x-python
|
PythonLexer
|
r1334 | """Nose Plugin that supports IPython doctests. | ||
Limitations: | ||||
- When generating examples for use as doctests, make sure that you have | ||||
|
r4872 | pretty-printing OFF. This can be done either by setting the | ||
``PlainTextFormatter.pprint`` option in your configuration file to False, or | ||||
|
r4468 | by interactively disabling it with %Pprint. This is required so that IPython | ||
|
r4872 | output matches that of normal Python, which is used by doctest for internal | ||
|
r1334 | execution. | ||
- Do not rely on specific prompt numbers for results (such as using | ||||
'_34==True', for example). For IPython tests run via an external process the | ||||
prompt numbers may be different, and IPython tests run as normal python code | ||||
won't even have these special _NN variables set at all. | ||||
""" | ||||
#----------------------------------------------------------------------------- | ||||
# Module imports | ||||
# From the standard library | ||||
|
r23129 | import builtins as builtin_mod | ||
|
r1334 | import doctest | ||
import inspect | ||||
import logging | ||||
import os | ||||
import re | ||||
import sys | ||||
|
r22954 | from importlib import import_module | ||
|
r23093 | from io import StringIO | ||
|
r1334 | |||
|
r22157 | from testpath import modified_env | ||
|
r1334 | from inspect import getmodule | ||
|
r1425 | |||
|
r26191 | from pathlib import Path, PurePath | ||
|
r1425 | # We are overriding the default doctest runner, so we need to import a few | ||
# things from doctest directly | ||||
from doctest import (REPORTING_FLAGS, REPORT_ONLY_FIRST_FAILURE, | ||||
_unittest_reportflags, DocTestRunner, | ||||
_extract_future_flags, pdb, _OutputRedirectingPdb, | ||||
_exception_traceback, | ||||
linecache) | ||||
|
r1334 | |||
# Third-party modules | ||||
from nose.plugins import doctests, Plugin | ||||
|
r22207 | from nose.util import anyp, tolist | ||
|
r1334 | |||
#----------------------------------------------------------------------------- | ||||
# Module globals and other constants | ||||
|
r2414 | #----------------------------------------------------------------------------- | ||
|
r1334 | |||
log = logging.getLogger(__name__) | ||||
|
r2414 | #----------------------------------------------------------------------------- | ||
|
r1377 | # Classes and functions | ||
|
r2414 | #----------------------------------------------------------------------------- | ||
|
r1377 | |||
def is_extension_module(filename): | ||||
"""Return whether the given filename is an extension module. | ||||
This simply checks that the extension is either .so or .pyd. | ||||
""" | ||||
return os.path.splitext(filename)[1].lower() in ('.so','.pyd') | ||||
|
r1764 | class DocTestSkip(object): | ||
"""Object wrapper for doctests to be skipped.""" | ||||
|
r4872 | |||
|
r1764 | ds_skip = """Doctest to skip. | ||
>>> 1 #doctest: +SKIP | ||||
""" | ||||
|
r1435 | def __init__(self,obj): | ||
self.obj = obj | ||||
def __getattribute__(self,key): | ||||
if key == '__doc__': | ||||
|
r1764 | return DocTestSkip.ds_skip | ||
|
r1435 | else: | ||
return getattr(object.__getattribute__(self,'obj'),key) | ||||
|
r1334 | # Modified version of the one in the stdlib, that fixes a python bug (doctests | ||
# not found in extension modules, http://bugs.python.org/issue3158) | ||||
class DocTestFinder(doctest.DocTestFinder): | ||||
def _from_module(self, module, object): | ||||
""" | ||||
Return true if the given object is defined in the given | ||||
module. | ||||
""" | ||||
if module is None: | ||||
return True | ||||
elif inspect.isfunction(object): | ||||
|
r13362 | return module.__dict__ is object.__globals__ | ||
|
r1334 | elif inspect.isbuiltin(object): | ||
return module.__name__ == object.__module__ | ||||
elif inspect.isclass(object): | ||||
return module.__name__ == object.__module__ | ||||
elif inspect.ismethod(object): | ||||
# This one may be a bug in cython that fails to correctly set the | ||||
# __module__ attribute of methods, but since the same error is easy | ||||
# to make by extension code writers, having this safety in place | ||||
# isn't such a bad idea | ||||
|
r13370 | return module.__name__ == object.__self__.__class__.__module__ | ||
|
r1334 | elif inspect.getmodule(object) is not None: | ||
return module is inspect.getmodule(object) | ||||
elif hasattr(object, '__module__'): | ||||
return module.__name__ == object.__module__ | ||||
elif isinstance(object, property): | ||||
return True # [XX] no way not be sure. | ||||
|
r14966 | elif inspect.ismethoddescriptor(object): | ||
# Unbound PyQt signals reach this point in Python 3.4b3, and we want | ||||
# to avoid throwing an error. See also http://bugs.python.org/issue3158 | ||||
return False | ||||
|
r1334 | else: | ||
|
r13373 | raise ValueError("object must be a class or function, got %r" % object) | ||
|
r1334 | |||
def _find(self, tests, obj, name, module, source_lines, globs, seen): | ||||
""" | ||||
Find tests for the given object and any contained objects, and | ||||
add them to `tests`. | ||||
""" | ||||
|
r21777 | print('_find for:', obj, name, module) # dbg | ||
|
r1435 | if hasattr(obj,"skip_doctest"): | ||
#print 'SKIPPING DOCTEST FOR:',obj # dbg | ||||
|
r1764 | obj = DocTestSkip(obj) | ||
|
r21777 | |||
|
r1334 | doctest.DocTestFinder._find(self,tests, obj, name, module, | ||
source_lines, globs, seen) | ||||
# Below we re-run pieces of the above method with manual modifications, | ||||
# because the original code is buggy and fails to correctly identify | ||||
# doctests in extension modules. | ||||
# Local shorthands | ||||
|
r22207 | from inspect import isroutine, isclass | ||
|
r1334 | |||
# Look for tests in a module's contained objects. | ||||
if inspect.ismodule(obj) and self._recurse: | ||||
for valname, val in obj.__dict__.items(): | ||||
valname1 = '%s.%s' % (name, valname) | ||||
if ( (isroutine(val) or isclass(val)) | ||||
and self._from_module(module, val) ): | ||||
self._find(tests, val, valname1, module, source_lines, | ||||
globs, seen) | ||||
# Look for tests in a class's contained objects. | ||||
if inspect.isclass(obj) and self._recurse: | ||||
#print 'RECURSE into class:',obj # dbg | ||||
for valname, val in obj.__dict__.items(): | ||||
# Special handling for staticmethod/classmethod. | ||||
if isinstance(val, staticmethod): | ||||
val = getattr(obj, valname) | ||||
if isinstance(val, classmethod): | ||||
|
r13370 | val = getattr(obj, valname).__func__ | ||
|
r1334 | |||
# Recurse to methods, properties, and nested classes. | ||||
if ((inspect.isfunction(val) or inspect.isclass(val) or | ||||
inspect.ismethod(val) or | ||||
isinstance(val, property)) and | ||||
self._from_module(module, val)): | ||||
valname = '%s.%s' % (name, valname) | ||||
self._find(tests, val, valname, module, source_lines, | ||||
globs, seen) | ||||
|
r1403 | class IPDoctestOutputChecker(doctest.OutputChecker): | ||
|
r1429 | """Second-chance checker with support for random tests. | ||
|
r4872 | |||
|
r1429 | If the default comparison doesn't pass, this checker looks in the expected | ||
output string for flags that tell us to ignore the output. | ||||
""" | ||||
|
r1453 | random_re = re.compile(r'#\s*random\s+') | ||
|
r4872 | |||
|
r1403 | def check_output(self, want, got, optionflags): | ||
|
r1429 | """Check output, accepting special markers embedded in the output. | ||
|
r1420 | |||
|
r1429 | If the output didn't pass the default validation but the special string | ||
'#random' is included, we accept it.""" | ||||
# Let the original tester verify first, in case people have valid tests | ||||
# that happen to have a comment saying '#random' embedded in. | ||||
|
r1420 | ret = doctest.OutputChecker.check_output(self, want, got, | ||
|
r1403 | optionflags) | ||
|
r1429 | if not ret and self.random_re.search(want): | ||
#print >> sys.stderr, 'RANDOM OK:',want # dbg | ||||
return True | ||||
|
r1403 | |||
return ret | ||||
|
r1334 | class DocTestCase(doctests.DocTestCase): | ||
"""Proxy for DocTestCase: provides an address() method that | ||||
returns the correct address for the doctest case. Otherwise | ||||
acts as a proxy to the test case. To provide hints for address(), | ||||
an obj may also be passed -- this will be used as the test object | ||||
for purposes of determining the test address, if it is provided. | ||||
""" | ||||
|
r1378 | # Note: this method was taken from numpy's nosetester module. | ||
|
r1420 | |||
# Subclass nose.plugins.doctests.DocTestCase to work around a bug in | ||||
|
r1378 | # its constructor that blocks non-default arguments from being passed | ||
# down into doctest.DocTestCase | ||||
|
r1403 | |||
def __init__(self, test, optionflags=0, setUp=None, tearDown=None, | ||||
checker=None, obj=None, result_var='_'): | ||||
self._result_var = result_var | ||||
|
r1420 | doctests.DocTestCase.__init__(self, test, | ||
|
r1403 | optionflags=optionflags, | ||
|
r1420 | setUp=setUp, tearDown=tearDown, | ||
|
r1403 | checker=checker) | ||
# Now we must actually copy the original constructor from the stdlib | ||||
# doctest class, because we can't call it directly and a bug in nose | ||||
# means it never gets passed the right arguments. | ||||
|
r1420 | |||
|
r1403 | self._dt_optionflags = optionflags | ||
self._dt_checker = checker | ||||
self._dt_test = test | ||||
|
r2445 | self._dt_test_globs_ori = test.globs | ||
|
r1403 | self._dt_setUp = setUp | ||
self._dt_tearDown = tearDown | ||||
|
r1334 | |||
|
r1509 | # XXX - store this runner once in the object! | ||
runner = IPDocTestRunner(optionflags=optionflags, | ||||
checker=checker, verbose=False) | ||||
self._dt_runner = runner | ||||
|
r2414 | # Each doctest should remember the directory it was loaded from, so | ||
# things like %run work without too many contortions | ||||
self._ori_dir = os.path.dirname(test.filename) | ||||
|
r1428 | |||
|
r1425 | # Modified runTest from the default stdlib | ||
def runTest(self): | ||||
test = self._dt_test | ||||
|
r1509 | runner = self._dt_runner | ||
|
r4872 | |||
|
r1425 | old = sys.stdout | ||
new = StringIO() | ||||
optionflags = self._dt_optionflags | ||||
if not (optionflags & REPORTING_FLAGS): | ||||
# The option flags don't include any reporting flags, | ||||
# so add the default reporting flags | ||||
optionflags |= _unittest_reportflags | ||||
try: | ||||
|
r1428 | # Save our current directory and switch out to the one where the | ||
# test was originally created, in case another doctest did a | ||||
# directory change. We'll restore this in the finally clause. | ||||
|
r23046 | curdir = os.getcwd() | ||
|
r2414 | #print 'runTest in dir:', self._ori_dir # dbg | ||
|
r1428 | os.chdir(self._ori_dir) | ||
|
r1425 | runner.DIVIDER = "-"*70 | ||
|
r1509 | failures, tries = runner.run(test,out=new.write, | ||
clear_globs=False) | ||||
|
r1425 | finally: | ||
sys.stdout = old | ||||
|
r1428 | os.chdir(curdir) | ||
|
r1425 | |||
if failures: | ||||
raise self.failureException(self.format_failure(new.getvalue())) | ||||
|
r1334 | |||
|
r1509 | def setUp(self): | ||
"""Modified test setup that syncs with ipython namespace""" | ||||
|
r2414 | #print "setUp test", self._dt_test.examples # dbg | ||
|
r7018 | if isinstance(self._dt_test.examples[0], IPExample): | ||
|
r1509 | # for IPython examples *only*, we swap the globals with the ipython | ||
# namespace, after updating it with the globals (which doctest | ||||
# fills with the necessary info from the module being tested). | ||||
|
r5456 | self.user_ns_orig = {} | ||
self.user_ns_orig.update(_ip.user_ns) | ||||
|
r2205 | _ip.user_ns.update(self._dt_test.globs) | ||
|
r7018 | # We must remove the _ key in the namespace, so that Python's | ||
# doctest code sets it naturally | ||||
_ip.user_ns.pop('_', None) | ||||
_ip.user_ns['__builtins__'] = builtin_mod | ||||
|
r2205 | self._dt_test.globs = _ip.user_ns | ||
|
r1509 | |||
|
r2134 | super(DocTestCase, self).setUp() | ||
def tearDown(self): | ||||
|
r2445 | |||
# Undo the test.globs reassignment we made, so that the parent class | ||||
# teardown doesn't destroy the ipython namespace | ||||
|
r7018 | if isinstance(self._dt_test.examples[0], IPExample): | ||
|
r2445 | self._dt_test.globs = self._dt_test_globs_ori | ||
|
r5456 | _ip.user_ns.clear() | ||
_ip.user_ns.update(self.user_ns_orig) | ||||
|
r4872 | |||
|
r2134 | # XXX - fperez: I am not sure if this is truly a bug in nose 0.11, but | ||
# it does look like one to me: its tearDown method tries to run | ||||
# | ||||
|
r13351 | # delattr(builtin_mod, self._result_var) | ||
|
r2134 | # | ||
# without checking that the attribute really is there; it implicitly | ||||
# assumes it should have been set via displayhook. But if the | ||||
# displayhook was never called, this doesn't necessarily happen. I | ||||
# haven't been able to find a little self-contained example outside of | ||||
# ipython that would show the problem so I can report it to the nose | ||||
# team, but it does happen a lot in our code. | ||||
# | ||||
# So here, we just protect as narrowly as possible by trapping an | ||||
# attribute error whose message would be the name of self._result_var, | ||||
# and letting any other error propagate. | ||||
try: | ||||
super(DocTestCase, self).tearDown() | ||||
|
r7787 | except AttributeError as exc: | ||
|
r2135 | if exc.args[0] != self._result_var: | ||
|
r2134 | raise | ||
|
r1482 | |||
|
r1378 | |||
|
r1334 | # A simple subclassing of the original with a different class name, so we can | ||
# distinguish and treat differently IPython examples from pure python ones. | ||||
class IPExample(doctest.Example): pass | ||||
|
r1377 | |||
|
r1334 | class IPExternalExample(doctest.Example): | ||
"""Doctest examples to be run in an external process.""" | ||||
def __init__(self, source, want, exc_msg=None, lineno=0, indent=0, | ||||
options=None): | ||||
# Parent constructor | ||||
doctest.Example.__init__(self,source,want,exc_msg,lineno,indent,options) | ||||
# An EXTRA newline is needed to prevent pexpect hangs | ||||
self.source += '\n' | ||||
|
r1377 | |||
|
r1334 | class IPDocTestParser(doctest.DocTestParser): | ||
""" | ||||
A class used to parse strings containing doctest examples. | ||||
Note: This is a version modified to properly recognize IPython input and | ||||
convert any IPython examples into valid Python ones. | ||||
""" | ||||
# This regular expression is used to find doctest examples in a | ||||
# string. It defines three groups: `source` is the source code | ||||
# (including leading indentation and prompts); `indent` is the | ||||
# indentation of the first (PS1) line of the source code; and | ||||
# `want` is the expected output (including leading indentation). | ||||
# Classic Python prompts or default IPython ones | ||||
_PS1_PY = r'>>>' | ||||
_PS2_PY = r'\.\.\.' | ||||
_PS1_IP = r'In\ \[\d+\]:' | ||||
_PS2_IP = r'\ \ \ \.\.\.+:' | ||||
_RE_TPL = r''' | ||||
# Source consists of a PS1 line followed by zero or more PS2 lines. | ||||
(?P<source> | ||||
(?:^(?P<indent> [ ]*) (?P<ps1> %s) .*) # PS1 line | ||||
(?:\n [ ]* (?P<ps2> %s) .*)*) # PS2 lines | ||||
\n? # a newline | ||||
# Want consists of any non-blank lines that do not start with PS1. | ||||
(?P<want> (?:(?![ ]*$) # Not a blank line | ||||
(?![ ]*%s) # Not a line starting with PS1 | ||||
(?![ ]*%s) # Not a line starting with PS2 | ||||
.*$\n? # But any other line | ||||
)*) | ||||
''' | ||||
_EXAMPLE_RE_PY = re.compile( _RE_TPL % (_PS1_PY,_PS2_PY,_PS1_PY,_PS2_PY), | ||||
re.MULTILINE | re.VERBOSE) | ||||
_EXAMPLE_RE_IP = re.compile( _RE_TPL % (_PS1_IP,_PS2_IP,_PS1_IP,_PS2_IP), | ||||
re.MULTILINE | re.VERBOSE) | ||||
|
r1430 | # Mark a test as being fully random. In this case, we simply append the | ||
# random marker ('#random') to each individual example's output. This way | ||||
# we don't need to modify any other code. | ||||
|
r1453 | _RANDOM_TEST = re.compile(r'#\s*all-random\s+') | ||
|
r1430 | |||
# Mark tests to be executed in an external process - currently unsupported. | ||||
|
r1429 | _EXTERNAL_IP = re.compile(r'#\s*ipdoctest:\s*EXTERNAL') | ||
|
r4872 | |||
|
r1334 | def ip2py(self,source): | ||
"""Convert input IPython source into valid Python.""" | ||||
|
r10754 | block = _ip.input_transformer_manager.transform_cell(source) | ||
if len(block.splitlines()) == 1: | ||||
return _ip.prefilter(block) | ||||
else: | ||||
return block | ||||
|
r1334 | |||
def parse(self, string, name='<string>'): | ||||
""" | ||||
Divide the given string into examples and intervening text, | ||||
and return them as a list of alternating Examples and strings. | ||||
Line numbers for the Examples are 0-based. The optional | ||||
argument `name` is a name identifying this string, and is only | ||||
used for error messages. | ||||
""" | ||||
|
r1420 | |||
|
r1403 | #print 'Parse string:\n',string # dbg | ||
|
r1334 | |||
string = string.expandtabs() | ||||
# If all lines begin with the same indentation, then strip it. | ||||
min_indent = self._min_indent(string) | ||||
if min_indent > 0: | ||||
string = '\n'.join([l[min_indent:] for l in string.split('\n')]) | ||||
output = [] | ||||
charno, lineno = 0, 0 | ||||
|
r1509 | # We make 'all random' tests by adding the '# random' mark to every | ||
# block of output in the test. | ||||
|
r1430 | if self._RANDOM_TEST.search(string): | ||
random_marker = '\n# random' | ||||
else: | ||||
random_marker = '' | ||||
|
r1334 | # Whether to convert the input from ipython to python syntax | ||
ip2py = False | ||||
# Find all doctest examples in the string. First, try them as Python | ||||
# examples, then as IPython ones | ||||
terms = list(self._EXAMPLE_RE_PY.finditer(string)) | ||||
if terms: | ||||
# Normal Python example | ||||
#print '-'*70 # dbg | ||||
#print 'PyExample, Source:\n',string # dbg | ||||
#print '-'*70 # dbg | ||||
Example = doctest.Example | ||||
else: | ||||
# It's an ipython example. Note that IPExamples are run | ||||
# in-process, so their syntax must be turned into valid python. | ||||
# IPExternalExamples are run out-of-process (via pexpect) so they | ||||
# don't need any filtering (a real ipython will be executing them). | ||||
terms = list(self._EXAMPLE_RE_IP.finditer(string)) | ||||
|
r1429 | if self._EXTERNAL_IP.search(string): | ||
|
r1334 | #print '-'*70 # dbg | ||
#print 'IPExternalExample, Source:\n',string # dbg | ||||
#print '-'*70 # dbg | ||||
Example = IPExternalExample | ||||
else: | ||||
#print '-'*70 # dbg | ||||
#print 'IPExample, Source:\n',string # dbg | ||||
#print '-'*70 # dbg | ||||
Example = IPExample | ||||
ip2py = True | ||||
for m in terms: | ||||
# Add the pre-example text to `output`. | ||||
output.append(string[charno:m.start()]) | ||||
# Update lineno (lines before this example) | ||||
lineno += string.count('\n', charno, m.start()) | ||||
# Extract info from the regexp match. | ||||
(source, options, want, exc_msg) = \ | ||||
self._parse_example(m, name, lineno,ip2py) | ||||
|
r1430 | |||
# Append the random-output marker (it defaults to empty in most | ||||
# cases, it's only non-empty for 'all-random' tests): | ||||
want += random_marker | ||||
|
r4872 | |||
|
r1334 | if Example is IPExternalExample: | ||
options[doctest.NORMALIZE_WHITESPACE] = True | ||||
want += '\n' | ||||
|
r1430 | |||
|
r1334 | # Create an Example, and add it to the list. | ||
if not self._IS_BLANK_OR_COMMENT(source): | ||||
output.append(Example(source, want, exc_msg, | ||||
lineno=lineno, | ||||
indent=min_indent+len(m.group('indent')), | ||||
options=options)) | ||||
# Update lineno (lines inside this example) | ||||
lineno += string.count('\n', m.start(), m.end()) | ||||
# Update charno. | ||||
charno = m.end() | ||||
# Add any remaining post-example text to `output`. | ||||
output.append(string[charno:]) | ||||
return output | ||||
def _parse_example(self, m, name, lineno,ip2py=False): | ||||
""" | ||||
Given a regular expression match from `_EXAMPLE_RE` (`m`), | ||||
return a pair `(source, want)`, where `source` is the matched | ||||
example's source code (with prompts and indentation stripped); | ||||
and `want` is the example's expected output (with indentation | ||||
stripped). | ||||
`name` is the string's name, and `lineno` is the line number | ||||
where the example starts; both are used for error messages. | ||||
Optional: | ||||
`ip2py`: if true, filter the input via IPython to convert the syntax | ||||
into valid python. | ||||
""" | ||||
# Get the example's indentation level. | ||||
indent = len(m.group('indent')) | ||||
# Divide source into lines; check that they're properly | ||||
# indented; and then strip their indentation & prompts. | ||||
source_lines = m.group('source').split('\n') | ||||
# We're using variable-length input prompts | ||||
ps1 = m.group('ps1') | ||||
ps2 = m.group('ps2') | ||||
ps1_len = len(ps1) | ||||
self._check_prompt_blank(source_lines, indent, name, lineno,ps1_len) | ||||
if ps2: | ||||
self._check_prefix(source_lines[1:], ' '*indent + ps2, name, lineno) | ||||
source = '\n'.join([sl[indent+ps1_len+1:] for sl in source_lines]) | ||||
if ip2py: | ||||
# Convert source input from IPython into valid Python syntax | ||||
source = self.ip2py(source) | ||||
# Divide want into lines; check that it's properly indented; and | ||||
# then strip the indentation. Spaces before the last newline should | ||||
# be preserved, so plain rstrip() isn't good enough. | ||||
want = m.group('want') | ||||
want_lines = want.split('\n') | ||||
if len(want_lines) > 1 and re.match(r' *$', want_lines[-1]): | ||||
del want_lines[-1] # forget final newline & spaces after it | ||||
self._check_prefix(want_lines, ' '*indent, name, | ||||
lineno + len(source_lines)) | ||||
# Remove ipython output prompt that might be present in the first line | ||||
want_lines[0] = re.sub(r'Out\[\d+\]: \s*?\n?','',want_lines[0]) | ||||
want = '\n'.join([wl[indent:] for wl in want_lines]) | ||||
# If `want` contains a traceback message, then extract it. | ||||
m = self._EXCEPTION_RE.match(want) | ||||
if m: | ||||
exc_msg = m.group('msg') | ||||
else: | ||||
exc_msg = None | ||||
# Extract options from the source. | ||||
options = self._find_options(source, name, lineno) | ||||
return source, options, want, exc_msg | ||||
def _check_prompt_blank(self, lines, indent, name, lineno, ps1_len): | ||||
""" | ||||
Given the lines of a source string (including prompts and | ||||
leading indentation), check to make sure that every prompt is | ||||
followed by a space character. If any line is not followed by | ||||
a space character, then raise ValueError. | ||||
Note: IPython-modified version which takes the input prompt length as a | ||||
parameter, so that prompts of variable length can be dealt with. | ||||
""" | ||||
space_idx = indent+ps1_len | ||||
min_len = space_idx+1 | ||||
for i, line in enumerate(lines): | ||||
if len(line) >= min_len and line[space_idx] != ' ': | ||||
raise ValueError('line %r of the docstring for %s ' | ||||
'lacks blank after %s: %r' % | ||||
(lineno+i+1, name, | ||||
line[indent:space_idx], line)) | ||||
|
r1425 | |||
|
r1334 | SKIP = doctest.register_optionflag('SKIP') | ||
|
r1427 | class IPDocTestRunner(doctest.DocTestRunner,object): | ||
"""Test runner that synchronizes the IPython namespace with test globals. | ||||
""" | ||||
|
r4872 | |||
|
r1420 | def run(self, test, compileflags=None, out=None, clear_globs=True): | ||
|
r1427 | # Hack: ipython needs access to the execution context of the example, | ||
# so that it can propagate user variables loaded by %run into | ||||
# test.globs. We put them here into our modified %run as a function | ||||
# attribute. Our new %run will then only make the namespace update | ||||
|
r25146 | # when called (rather than unconditionally updating test.globs here | ||
|
r1427 | # for all examples, most of which won't be calling %run anyway). | ||
|
r2414 | #_ip._ipdoctest_test_globs = test.globs | ||
#_ip._ipdoctest_test_filename = test.filename | ||||
test.globs.update(_ip.user_ns) | ||||
|
r4872 | |||
|
r22157 | # Override terminal size to standardise traceback format | ||
with modified_env({'COLUMNS': '80', 'LINES': '24'}): | ||||
return super(IPDocTestRunner,self).run(test, | ||||
compileflags,out,clear_globs) | ||||
|
r1420 | |||
|
r1334 | class DocFileCase(doctest.DocFileCase): | ||
"""Overrides to provide filename | ||||
""" | ||||
def address(self): | ||||
return (self._dt_test.filename, None, None) | ||||
class ExtensionDoctest(doctests.Doctest): | ||||
"""Nose Plugin that supports doctests in extension modules. | ||||
""" | ||||
name = 'extdoctest' # call nosetests with --with-extdoctest | ||||
enabled = True | ||||
def options(self, parser, env=os.environ): | ||||
Plugin.options(self, parser, env) | ||||
|
r1568 | parser.add_option('--doctest-tests', action='store_true', | ||
dest='doctest_tests', | ||||
default=env.get('NOSE_DOCTEST_TESTS',True), | ||||
help="Also look for doctests in test modules. " | ||||
"Note that classes, methods and functions should " | ||||
"have either doctests or non-doctest tests, " | ||||
"not both. [NOSE_DOCTEST_TESTS]") | ||||
parser.add_option('--doctest-extension', action="append", | ||||
dest="doctestExtension", | ||||
help="Also look for doctests in files with " | ||||
"this extension [NOSE_DOCTEST_EXTENSION]") | ||||
# Set the default as a list, if given in env; otherwise | ||||
# an additional value set on the command line will cause | ||||
# an error. | ||||
env_setting = env.get('NOSE_DOCTEST_EXTENSION') | ||||
if env_setting is not None: | ||||
parser.set_defaults(doctestExtension=tolist(env_setting)) | ||||
|
r1334 | |||
def configure(self, options, config): | ||||
Plugin.configure(self, options, config) | ||||
|
r4567 | # Pull standard doctest plugin out of config; we will do doctesting | ||
config.plugins.plugins = [p for p in config.plugins.plugins | ||||
if p.name != 'doctest'] | ||||
|
r1334 | self.doctest_tests = options.doctest_tests | ||
self.extension = tolist(options.doctestExtension) | ||||
|
r1509 | |||
|
r1334 | self.parser = doctest.DocTestParser() | ||
|
r1509 | self.finder = DocTestFinder() | ||
self.checker = IPDoctestOutputChecker() | ||||
|
r1420 | self.globs = None | ||
self.extraglobs = None | ||||
|
r1334 | |||
|
r1761 | |||
|
r1334 | def loadTestsFromExtensionModule(self,filename): | ||
bpath,mod = os.path.split(filename) | ||||
modname = os.path.splitext(mod)[0] | ||||
try: | ||||
sys.path.append(bpath) | ||||
|
r22954 | module = import_module(modname) | ||
|
r1334 | tests = list(self.loadTestsFromModule(module)) | ||
finally: | ||||
sys.path.pop() | ||||
return tests | ||||
|
r1403 | # NOTE: the method below is almost a copy of the original one in nose, with | ||
# a few modifications to control output checking. | ||||
|
r1420 | |||
|
r1403 | def loadTestsFromModule(self, module): | ||
|
r1761 | #print '*** ipdoctest - lTM',module # dbg | ||
|
r4872 | |||
|
r1403 | if not self.matches(module.__name__): | ||
log.debug("Doctest doesn't want module %s", module) | ||||
return | ||||
|
r1420 | |||
tests = self.finder.find(module,globs=self.globs, | ||||
extraglobs=self.extraglobs) | ||||
|
r1403 | if not tests: | ||
return | ||||
|
r1428 | |||
|
r1509 | # always use whitespace and ellipsis options | ||
optionflags = doctest.NORMALIZE_WHITESPACE | doctest.ELLIPSIS | ||||
|
r1403 | tests.sort() | ||
module_file = module.__file__ | ||||
if module_file[-4:] in ('.pyc', '.pyo'): | ||||
module_file = module_file[:-1] | ||||
for test in tests: | ||||
if not test.examples: | ||||
continue | ||||
if not test.filename: | ||||
test.filename = module_file | ||||
|
r4872 | |||
|
r1420 | yield DocTestCase(test, | ||
|
r1403 | optionflags=optionflags, | ||
|
r1509 | checker=self.checker) | ||
|
r1403 | |||
|
r1334 | def loadTestsFromFile(self, filename): | ||
|
r2414 | #print "ipdoctest - from file", filename # dbg | ||
|
r1334 | if is_extension_module(filename): | ||
for t in self.loadTestsFromExtensionModule(filename): | ||||
yield t | ||||
else: | ||||
|
r1420 | if self.extension and anyp(filename.endswith, self.extension): | ||
|
r26191 | name = PurePath(filename).name | ||
doc = Path(filename).read_text() | ||||
|
r1420 | test = self.parser.get_doctest( | ||
doc, globs={'__file__': filename}, name=name, | ||||
filename=filename, lineno=0) | ||||
if test.examples: | ||||
#print 'FileCase:',test.examples # dbg | ||||
yield DocFileCase(test) | ||||
else: | ||||
yield False # no tests to load | ||||
|
r1334 | |||
|
r1377 | |||
|
r1334 | class IPythonDoctest(ExtensionDoctest): | ||
"""Nose Plugin that supports doctests in extension modules. | ||||
""" | ||||
name = 'ipdoctest' # call nosetests with --with-ipdoctest | ||||
enabled = True | ||||
|
r2414 | |||
|
r1763 | def makeTest(self, obj, parent): | ||
"""Look for doctests in the given object, which will be a | ||||
function, method or class. | ||||
""" | ||||
|
r2414 | #print 'Plugin analyzing:', obj, parent # dbg | ||
|
r1763 | # always use whitespace and ellipsis options | ||
optionflags = doctest.NORMALIZE_WHITESPACE | doctest.ELLIPSIS | ||||
doctests = self.finder.find(obj, module=getmodule(parent)) | ||||
if doctests: | ||||
for test in doctests: | ||||
if len(test.examples) == 0: | ||||
continue | ||||
yield DocTestCase(test, obj=obj, | ||||
optionflags=optionflags, | ||||
checker=self.checker) | ||||
|
r1910 | def options(self, parser, env=os.environ): | ||
|
r2414 | #print "Options for nose plugin:", self.name # dbg | ||
|
r1910 | Plugin.options(self, parser, env) | ||
parser.add_option('--ipdoctest-tests', action='store_true', | ||||
dest='ipdoctest_tests', | ||||
default=env.get('NOSE_IPDOCTEST_TESTS',True), | ||||
help="Also look for doctests in test modules. " | ||||
"Note that classes, methods and functions should " | ||||
"have either doctests or non-doctest tests, " | ||||
"not both. [NOSE_IPDOCTEST_TESTS]") | ||||
parser.add_option('--ipdoctest-extension', action="append", | ||||
|
r1914 | dest="ipdoctest_extension", | ||
|
r1910 | help="Also look for doctests in files with " | ||
"this extension [NOSE_IPDOCTEST_EXTENSION]") | ||||
# Set the default as a list, if given in env; otherwise | ||||
# an additional value set on the command line will cause | ||||
# an error. | ||||
env_setting = env.get('NOSE_IPDOCTEST_EXTENSION') | ||||
if env_setting is not None: | ||||
|
r1914 | parser.set_defaults(ipdoctest_extension=tolist(env_setting)) | ||
|
r1334 | |||
|
r1910 | def configure(self, options, config): | ||
|
r2414 | #print "Configuring nose plugin:", self.name # dbg | ||
|
r1334 | Plugin.configure(self, options, config) | ||
|
r4567 | # Pull standard doctest plugin out of config; we will do doctesting | ||
config.plugins.plugins = [p for p in config.plugins.plugins | ||||
if p.name != 'doctest'] | ||||
|
r1910 | self.doctest_tests = options.ipdoctest_tests | ||
|
r1914 | self.extension = tolist(options.ipdoctest_extension) | ||
|
r1509 | |||
|
r1334 | self.parser = IPDocTestParser() | ||
self.finder = DocTestFinder(parser=self.parser) | ||||
|
r1509 | self.checker = IPDoctestOutputChecker() | ||
|
r1420 | self.globs = None | ||
self.extraglobs = None | ||||