include all modules in doctests

This patch changes doctest's test finder to include all files in the nutils
directory, rather than the ones listed in nutils.__all__ which is due to be
removed. The change includes a modified version of DocTestFinder to fix a bug
triggered by the SI module (formerly untested) and for which a PR is created
for cpython (python/cpython#107716). The patch also
includes a small fix in SI's documentation.

Author: gertjanvanzwieten

nutils/SI.py

@@ -12,6 +12,7 @@
 prefixes. Dimensional values are generated primarily by instantiating the
 Quantity type with a string value.
 
+    >>> from nutils import SI
     >>> v = SI.parse('7μN*5h/6g')
 
 The Quantity constructor recognizes the multiplication (\*) and division (/)

nutils/testing.py

@@ -17,6 +17,7 @@
 import warnings as _builtin_warnings
 import logging
 import numpy
+import inspect
 from nutils import warnings, numeric
 
 
@@ -316,4 +317,62 @@ def _parse_array_tokens(cls, tokens):
         else:
             return float(token)
 
+
+class DocTestFinder(doctest.DocTestFinder):
+
+    # This is a modified version of doctest.DocTestFinder to fix issue
+    # https://github.com/python/cpython/issues/107715, which prevents doctest
+    # operation for the SI module. The modification assumes that `find`
+    # continues to rely on the internal `_find_lineno` method, which will
+    # hopefully be the case until Python merges #107716.
+
+    def _find_lineno(self, obj, source_lines):
+        """
+        Return a line number of the given object's docstring.  Note:
+        this method assumes that the object has a docstring.
+        """
+        lineno = None
+
+        # Find the line number for modules.
+        if inspect.ismodule(obj):
+            lineno = 0
+
+        # Find the line number for classes.
+        # Note: this could be fooled if a class is defined multiple
+        # times in a single file.
+        if inspect.isclass(obj):
+            if source_lines is None:
+                return None
+            pat = re.compile(r'^\s*class\s*%s\b' %
+                             re.escape(getattr(obj, '__name__', '-')))
+            for i, line in enumerate(source_lines):
+                if pat.match(line):
+                    lineno = i
+                    break
+
+        # Find the line number for functions & methods.
+        if inspect.ismethod(obj): obj = obj.__func__
+        if inspect.isfunction(obj): obj = obj.__code__
+        if inspect.istraceback(obj): obj = obj.tb_frame
+        if inspect.isframe(obj): obj = obj.f_code
+        if inspect.iscode(obj):
+            lineno = getattr(obj, 'co_firstlineno', None)-1
+
+        # Find the line number where the docstring starts.  Assume
+        # that it's the first line that begins with a quote mark.
+        # Note: this could be fooled by a multiline function
+        # signature, where a continuation line begins with a quote
+        # mark.
+        if lineno is not None:
+            if source_lines is None:
+                return lineno+1
+            pat = re.compile(r'(^|.*:)\s*\w*("|\')')
+            for lineno in range(lineno, len(source_lines)):
+                if pat.match(source_lines[lineno]):
+                    return lineno
+
+        # We couldn't find the line number.
+        return None
+
+
 # vim:sw=4:sts=4:et

tests/test_docs.py

@@ -59,11 +59,11 @@ def __repr__(self):
 
 doctest = unittest.TestSuite()
 parser = _doctest.DocTestParser()
-finder = _doctest.DocTestFinder(parser=parser)
+finder = nutils.testing.DocTestFinder(parser=parser)
 checker = nutils.testing.FloatNeighborhoodOutputChecker()
 root = pathlib.Path(__file__).parent.parent
-for name in nutils.__all__:
-    module = importlib.import_module('.'+name, 'nutils')
+for path in sorted((root/'nutils').glob('*.py')):
+    module = importlib.import_module('.'+path.stem, 'nutils')
     for test in sorted(finder.find(module)):
         if len(test.examples) == 0:
             continue