Chris@87: # These classes implement a doctest runner plugin for nose, a "known failure"
Chris@87: # error class, and a customized TestProgram for NumPy.
Chris@87: 
Chris@87: # Because this module imports nose directly, it should not
Chris@87: # be used except by nosetester.py to avoid a general NumPy
Chris@87: # dependency on nose.
Chris@87: from __future__ import division, absolute_import, print_function
Chris@87: 
Chris@87: import os
Chris@87: import doctest
Chris@87: 
Chris@87: import nose
Chris@87: from nose.plugins import doctests as npd
Chris@87: from nose.plugins.errorclass import ErrorClass, ErrorClassPlugin
Chris@87: from nose.plugins.base import Plugin
Chris@87: from nose.util import src
Chris@87: import numpy
Chris@87: from .nosetester import get_package_name
Chris@87: import inspect
Chris@87: 
Chris@87: # Some of the classes in this module begin with 'Numpy' to clearly distinguish
Chris@87: # them from the plethora of very similar names from nose/unittest/doctest
Chris@87: 
Chris@87: #-----------------------------------------------------------------------------
Chris@87: # Modified version of the one in the stdlib, that fixes a python bug (doctests
Chris@87: # not found in extension modules, http://bugs.python.org/issue3158)
Chris@87: class NumpyDocTestFinder(doctest.DocTestFinder):
Chris@87: 
Chris@87:     def _from_module(self, module, object):
Chris@87:         """
Chris@87:         Return true if the given object is defined in the given
Chris@87:         module.
Chris@87:         """
Chris@87:         if module is None:
Chris@87:             #print '_fm C1'  # dbg
Chris@87:             return True
Chris@87:         elif inspect.isfunction(object):
Chris@87:             #print '_fm C2'  # dbg
Chris@87:             return module.__dict__ is object.__globals__
Chris@87:         elif inspect.isbuiltin(object):
Chris@87:             #print '_fm C2-1'  # dbg
Chris@87:             return module.__name__ == object.__module__
Chris@87:         elif inspect.isclass(object):
Chris@87:             #print '_fm C3'  # dbg
Chris@87:             return module.__name__ == object.__module__
Chris@87:         elif inspect.ismethod(object):
Chris@87:             # This one may be a bug in cython that fails to correctly set the
Chris@87:             # __module__ attribute of methods, but since the same error is easy
Chris@87:             # to make by extension code writers, having this safety in place
Chris@87:             # isn't such a bad idea
Chris@87:             #print '_fm C3-1'  # dbg
Chris@87:             return module.__name__ == object.__self__.__class__.__module__
Chris@87:         elif inspect.getmodule(object) is not None:
Chris@87:             #print '_fm C4'  # dbg
Chris@87:             #print 'C4 mod',module,'obj',object # dbg
Chris@87:             return module is inspect.getmodule(object)
Chris@87:         elif hasattr(object, '__module__'):
Chris@87:             #print '_fm C5'  # dbg
Chris@87:             return module.__name__ == object.__module__
Chris@87:         elif isinstance(object, property):
Chris@87:             #print '_fm C6'  # dbg
Chris@87:             return True # [XX] no way not be sure.
Chris@87:         else:
Chris@87:             raise ValueError("object must be a class or function")
Chris@87: 
Chris@87:     def _find(self, tests, obj, name, module, source_lines, globs, seen):
Chris@87:         """
Chris@87:         Find tests for the given object and any contained objects, and
Chris@87:         add them to `tests`.
Chris@87:         """
Chris@87: 
Chris@87:         doctest.DocTestFinder._find(self, tests, obj, name, module,
Chris@87:                                     source_lines, globs, seen)
Chris@87: 
Chris@87:         # Below we re-run pieces of the above method with manual modifications,
Chris@87:         # because the original code is buggy and fails to correctly identify
Chris@87:         # doctests in extension modules.
Chris@87: 
Chris@87:         # Local shorthands
Chris@87:         from inspect import isroutine, isclass, ismodule, isfunction, \
Chris@87:                             ismethod
Chris@87: 
Chris@87:         # Look for tests in a module's contained objects.
Chris@87:         if ismodule(obj) and self._recurse:
Chris@87:             for valname, val in obj.__dict__.items():
Chris@87:                 valname1 = '%s.%s' % (name, valname)
Chris@87:                 if ( (isroutine(val) or isclass(val))
Chris@87:                      and self._from_module(module, val) ):
Chris@87: 
Chris@87:                     self._find(tests, val, valname1, module, source_lines,
Chris@87:                                globs, seen)
Chris@87: 
Chris@87: 
Chris@87:         # Look for tests in a class's contained objects.
Chris@87:         if isclass(obj) and self._recurse:
Chris@87:             #print 'RECURSE into class:',obj  # dbg
Chris@87:             for valname, val in obj.__dict__.items():
Chris@87:                 #valname1 = '%s.%s' % (name, valname)  # dbg
Chris@87:                 #print 'N',name,'VN:',valname,'val:',str(val)[:77] # dbg
Chris@87:                 # Special handling for staticmethod/classmethod.
Chris@87:                 if isinstance(val, staticmethod):
Chris@87:                     val = getattr(obj, valname)
Chris@87:                 if isinstance(val, classmethod):
Chris@87:                     val = getattr(obj, valname).__func__
Chris@87: 
Chris@87:                 # Recurse to methods, properties, and nested classes.
Chris@87:                 if ((isfunction(val) or isclass(val) or
Chris@87:                      ismethod(val) or isinstance(val, property)) and
Chris@87:                       self._from_module(module, val)):
Chris@87:                     valname = '%s.%s' % (name, valname)
Chris@87:                     self._find(tests, val, valname, module, source_lines,
Chris@87:                                globs, seen)
Chris@87: 
Chris@87: 
Chris@87: # second-chance checker; if the default comparison doesn't
Chris@87: # pass, then see if the expected output string contains flags that
Chris@87: # tell us to ignore the output
Chris@87: class NumpyOutputChecker(doctest.OutputChecker):
Chris@87:     def check_output(self, want, got, optionflags):
Chris@87:         ret = doctest.OutputChecker.check_output(self, want, got,
Chris@87:                                                  optionflags)
Chris@87:         if not ret:
Chris@87:             if "#random" in want:
Chris@87:                 return True
Chris@87: 
Chris@87:             # it would be useful to normalize endianness so that
Chris@87:             # bigendian machines don't fail all the tests (and there are
Chris@87:             # actually some bigendian examples in the doctests). Let's try
Chris@87:             # making them all little endian
Chris@87:             got = got.replace("'>", "'<")
Chris@87:             want= want.replace("'>", "'<")
Chris@87: 
Chris@87:             # try to normalize out 32 and 64 bit default int sizes
Chris@87:             for sz in [4, 8]:
Chris@87:                 got = got.replace("'<i%d'"%sz, "int")
Chris@87:                 want= want.replace("'<i%d'"%sz, "int")
Chris@87: 
Chris@87:             ret = doctest.OutputChecker.check_output(self, want,
Chris@87:                     got, optionflags)
Chris@87: 
Chris@87:         return ret
Chris@87: 
Chris@87: 
Chris@87: # Subclass nose.plugins.doctests.DocTestCase to work around a bug in
Chris@87: # its constructor that blocks non-default arguments from being passed
Chris@87: # down into doctest.DocTestCase
Chris@87: class NumpyDocTestCase(npd.DocTestCase):
Chris@87:     def __init__(self, test, optionflags=0, setUp=None, tearDown=None,
Chris@87:                  checker=None, obj=None, result_var='_'):
Chris@87:         self._result_var = result_var
Chris@87:         self._nose_obj = obj
Chris@87:         doctest.DocTestCase.__init__(self, test,
Chris@87:                                      optionflags=optionflags,
Chris@87:                                      setUp=setUp, tearDown=tearDown,
Chris@87:                                      checker=checker)
Chris@87: 
Chris@87: 
Chris@87: print_state = numpy.get_printoptions()
Chris@87: 
Chris@87: class NumpyDoctest(npd.Doctest):
Chris@87:     name = 'numpydoctest'   # call nosetests with --with-numpydoctest
Chris@87:     score = 1000 # load late, after doctest builtin
Chris@87: 
Chris@87:     # always use whitespace and ellipsis options for doctests
Chris@87:     doctest_optflags = doctest.NORMALIZE_WHITESPACE | doctest.ELLIPSIS
Chris@87: 
Chris@87:     # files that should be ignored for doctests
Chris@87:     doctest_ignore = ['generate_numpy_api.py',
Chris@87:                       'setup.py']
Chris@87: 
Chris@87:     # Custom classes; class variables to allow subclassing
Chris@87:     doctest_case_class = NumpyDocTestCase
Chris@87:     out_check_class = NumpyOutputChecker
Chris@87:     test_finder_class = NumpyDocTestFinder
Chris@87: 
Chris@87:     # Don't use the standard doctest option handler; hard-code the option values
Chris@87:     def options(self, parser, env=os.environ):
Chris@87:         Plugin.options(self, parser, env)
Chris@87:         # Test doctests in 'test' files / directories. Standard plugin default
Chris@87:         # is False
Chris@87:         self.doctest_tests = True
Chris@87:         # Variable name; if defined, doctest results stored in this variable in
Chris@87:         # the top-level namespace.  None is the standard default
Chris@87:         self.doctest_result_var = None
Chris@87: 
Chris@87:     def configure(self, options, config):
Chris@87:         # parent method sets enabled flag from command line --with-numpydoctest
Chris@87:         Plugin.configure(self, options, config)
Chris@87:         self.finder = self.test_finder_class()
Chris@87:         self.parser = doctest.DocTestParser()
Chris@87:         if self.enabled:
Chris@87:             # Pull standard doctest out of plugin list; there's no reason to run
Chris@87:             # both.  In practice the Unplugger plugin above would cover us when
Chris@87:             # run from a standard numpy.test() call; this is just in case
Chris@87:             # someone wants to run our plugin outside the numpy.test() machinery
Chris@87:             config.plugins.plugins = [p for p in config.plugins.plugins
Chris@87:                                       if p.name != 'doctest']
Chris@87: 
Chris@87:     def set_test_context(self, test):
Chris@87:         """ Configure `test` object to set test context
Chris@87: 
Chris@87:         We set the numpy / scipy standard doctest namespace
Chris@87: 
Chris@87:         Parameters
Chris@87:         ----------
Chris@87:         test : test object
Chris@87:             with ``globs`` dictionary defining namespace
Chris@87: 
Chris@87:         Returns
Chris@87:         -------
Chris@87:         None
Chris@87: 
Chris@87:         Notes
Chris@87:         -----
Chris@87:         `test` object modified in place
Chris@87:         """
Chris@87:         # set the namespace for tests
Chris@87:         pkg_name = get_package_name(os.path.dirname(test.filename))
Chris@87: 
Chris@87:         # Each doctest should execute in an environment equivalent to
Chris@87:         # starting Python and executing "import numpy as np", and,
Chris@87:         # for SciPy packages, an additional import of the local
Chris@87:         # package (so that scipy.linalg.basic.py's doctests have an
Chris@87:         # implicit "from scipy import linalg" as well.
Chris@87:         #
Chris@87:         # Note: __file__ allows the doctest in NoseTester to run
Chris@87:         # without producing an error
Chris@87:         test.globs = {'__builtins__':__builtins__,
Chris@87:                       '__file__':'__main__',
Chris@87:                       '__name__':'__main__',
Chris@87:                       'np':numpy}
Chris@87:         # add appropriate scipy import for SciPy tests
Chris@87:         if 'scipy' in pkg_name:
Chris@87:             p = pkg_name.split('.')
Chris@87:             p2 = p[-1]
Chris@87:             test.globs[p2] = __import__(pkg_name, test.globs, {}, [p2])
Chris@87: 
Chris@87:     # Override test loading to customize test context (with set_test_context
Chris@87:     # method), set standard docstring options, and install our own test output
Chris@87:     # checker
Chris@87:     def loadTestsFromModule(self, module):
Chris@87:         if not self.matches(module.__name__):
Chris@87:             npd.log.debug("Doctest doesn't want module %s", module)
Chris@87:             return
Chris@87:         try:
Chris@87:             tests = self.finder.find(module)
Chris@87:         except AttributeError:
Chris@87:             # nose allows module.__test__ = False; doctest does not and
Chris@87:             # throws AttributeError
Chris@87:             return
Chris@87:         if not tests:
Chris@87:             return
Chris@87:         tests.sort()
Chris@87:         module_file = src(module.__file__)
Chris@87:         for test in tests:
Chris@87:             if not test.examples:
Chris@87:                 continue
Chris@87:             if not test.filename:
Chris@87:                 test.filename = module_file
Chris@87:             # Set test namespace; test altered in place
Chris@87:             self.set_test_context(test)
Chris@87:             yield self.doctest_case_class(test,
Chris@87:                                           optionflags=self.doctest_optflags,
Chris@87:                                           checker=self.out_check_class(),
Chris@87:                                           result_var=self.doctest_result_var)
Chris@87: 
Chris@87:     # Add an afterContext method to nose.plugins.doctests.Doctest in order
Chris@87:     # to restore print options to the original state after each doctest
Chris@87:     def afterContext(self):
Chris@87:         numpy.set_printoptions(**print_state)
Chris@87: 
Chris@87:     # Ignore NumPy-specific build files that shouldn't be searched for tests
Chris@87:     def wantFile(self, file):
Chris@87:         bn = os.path.basename(file)
Chris@87:         if bn in self.doctest_ignore:
Chris@87:             return False
Chris@87:         return npd.Doctest.wantFile(self, file)
Chris@87: 
Chris@87: 
Chris@87: class Unplugger(object):
Chris@87:     """ Nose plugin to remove named plugin late in loading
Chris@87: 
Chris@87:     By default it removes the "doctest" plugin.
Chris@87:     """
Chris@87:     name = 'unplugger'
Chris@87:     enabled = True # always enabled
Chris@87:     score = 4000 # load late in order to be after builtins
Chris@87: 
Chris@87:     def __init__(self, to_unplug='doctest'):
Chris@87:         self.to_unplug = to_unplug
Chris@87: 
Chris@87:     def options(self, parser, env):
Chris@87:         pass
Chris@87: 
Chris@87:     def configure(self, options, config):
Chris@87:         # Pull named plugin out of plugins list
Chris@87:         config.plugins.plugins = [p for p in config.plugins.plugins
Chris@87:                                   if p.name != self.to_unplug]
Chris@87: 
Chris@87: 
Chris@87: class KnownFailureTest(Exception):
Chris@87:     '''Raise this exception to mark a test as a known failing test.'''
Chris@87:     pass
Chris@87: 
Chris@87: 
Chris@87: class KnownFailure(ErrorClassPlugin):
Chris@87:     '''Plugin that installs a KNOWNFAIL error class for the
Chris@87:     KnownFailureClass exception.  When KnownFailureTest is raised,
Chris@87:     the exception will be logged in the knownfail attribute of the
Chris@87:     result, 'K' or 'KNOWNFAIL' (verbose) will be output, and the
Chris@87:     exception will not be counted as an error or failure.'''
Chris@87:     enabled = True
Chris@87:     knownfail = ErrorClass(KnownFailureTest,
Chris@87:                            label='KNOWNFAIL',
Chris@87:                            isfailure=False)
Chris@87: 
Chris@87:     def options(self, parser, env=os.environ):
Chris@87:         env_opt = 'NOSE_WITHOUT_KNOWNFAIL'
Chris@87:         parser.add_option('--no-knownfail', action='store_true',
Chris@87:                           dest='noKnownFail', default=env.get(env_opt, False),
Chris@87:                           help='Disable special handling of KnownFailureTest '
Chris@87:                                'exceptions')
Chris@87: 
Chris@87:     def configure(self, options, conf):
Chris@87:         if not self.can_configure:
Chris@87:             return
Chris@87:         self.conf = conf
Chris@87:         disable = getattr(options, 'noKnownFail', False)
Chris@87:         if disable:
Chris@87:             self.enabled = False
Chris@87: 
Chris@87: 
Chris@87: # Class allows us to save the results of the tests in runTests - see runTests
Chris@87: # method docstring for details
Chris@87: class NumpyTestProgram(nose.core.TestProgram):
Chris@87:     def runTests(self):
Chris@87:         """Run Tests. Returns true on success, false on failure, and
Chris@87:         sets self.success to the same value.
Chris@87: 
Chris@87:         Because nose currently discards the test result object, but we need
Chris@87:         to return it to the user, override TestProgram.runTests to retain
Chris@87:         the result
Chris@87:         """
Chris@87:         if self.testRunner is None:
Chris@87:             self.testRunner = nose.core.TextTestRunner(stream=self.config.stream,
Chris@87:                                                        verbosity=self.config.verbosity,
Chris@87:                                                        config=self.config)
Chris@87:         plug_runner = self.config.plugins.prepareTestRunner(self.testRunner)
Chris@87:         if plug_runner is not None:
Chris@87:             self.testRunner = plug_runner
Chris@87:         self.result = self.testRunner.run(self.test)
Chris@87:         self.success = self.result.wasSuccessful()
Chris@87:         return self.success