Improves docassert with C++ functions (#18)

xadupre · web-flow · commit d229036a8f14 · 2023-07-27T00:17:17.000+02:00
* Improves docassrt with C++ functions

* catch more exceptions

* fix one last issue
diff --git a/_unittests/ut_docassert/test_docassert_cpp.py b/_unittests/ut_docassert/test_docassert_cpp.py
@@ -0,0 +1,61 @@
+import unittest
+from sphinx_runpython.ext_test_case import ExtTestCase
+from sphinx_runpython.import_object_helper import import_object
+from sphinx_runpython.docassert.sphinx_docassert_extension import parse_signature
+
+
+class TestDocAssertCpp(ExtTestCase):
+    def test_import_object1(self):
+        name = "onnx_extended.ortcy.wrap.ortinf.OrtSession"
+        try:
+            obj, new_name = import_object(name, kind="class")
+        except (ImportError, RuntimeError):
+            return
+        self.assertEqual(name.split(".")[-1], new_name)
+        self.assertEqual(obj.__text_signature__, "($self, /, *args, **kwargs)")
+
+    def test_import_object2(self):
+        name = "onnx_extended.validation.cpu._validation.benchmark_cache"
+        try:
+            obj, new_name = import_object(name, kind="function")
+        except (ImportError, RuntimeError):
+            return
+        self.assertEqual(name.split(".")[-1], new_name)
+        self.assertEmpty(obj.__text_signature__)
+        sig = parse_signature(obj.__doc__)
+        self.assertEqual(
+            repr(sig), "benchmark_cache(size: int, verbose: bool = True) -> float"
+        )
+        self.assertIn("size", sig.param_names)
+
+    def test_import_object3(self):
+        name = "onnx_extended.validation.cython.vector_function_cy.vector_add_c"
+        try:
+            obj, new_name = import_object(name, kind="function")
+        except (ImportError, RuntimeError):
+            return
+        self.assertEqual(name.split(".")[-1], new_name)
+        self.assertIn("vector_add_c(v1, v2)", obj.__doc__)
+        sig = parse_signature(obj.__doc__)
+        self.assertEqual(repr(sig), "vector_add_c(v1, v2)")
+        self.assertIn("v1", sig.param_names)
+
+    def test_extract_signature(self):
+        sig = (
+            "benchmark_cache(size: int, verbose: bool = True) -> float\n\n "
+            "Runs a benchmark to measure the cache performance.\nThe function "
+            "measures the time for N random accesses in array of size N\nand "
+            "returns the time divided by N.\nIt copies random elements taken "
+            "from the array size to random\nposition in another of the same size. "
+            "It does that *size* times\nand return the average time per move."
+            "\nSee example :ref:`l-example-bench-cpu`.\n\n"
+            ":param size: array size\n:return: average time per move\n\n'"
+        )
+        res = parse_signature(sig)
+        self.assertEqual(
+            repr(res), "benchmark_cache(size: int, verbose: bool = True) -> float"
+        )
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)
diff --git a/sphinx_runpython/docassert/sphinx_docassert_extension.py b/sphinx_runpython/docassert/sphinx_docassert_extension.py
@@ -4,7 +4,7 @@
 import sphinx
 from sphinx.util import logging
 from sphinx.util.docfields import DocFieldTransformer, _is_single_paragraph
-from ..import_object_helper import import_any_object
+from ..import_object_helper import import_any_object, import_object
 
 
 class Parameter:
@@ -15,6 +15,8 @@ def __init__(self, name: str, dtype: type):
         self.dtype = dtype
 
     def __repr__(self):
+        if self.dtype is None:
+            return self.name
         return f"{self.name}: {self.dtype}"
 
 
@@ -35,23 +37,33 @@ def __repr__(self):
         for p in self.params:
             ps.append(repr(p))
         els.append(", ".join(ps))
-        els.extend([")", " -> ", self.result_type])
+        if self.result_type is None:
+            els.append(")")
+        else:
+            els.extend([")", " -> ", self.result_type])
         return "".join(els)
 
+    @property
+    def param_names(self):
+        return set(el.name for el in self.params)
+
 
 def parse_signature(text: str) -> Signature:
-    reg = re.compile("([_a-zA-Z][_a-zA-Z0-9]*?)[(](.*?)[)] -> ([a-zA-Z0-9]+)")
+    reg = re.compile("([_a-zA-Z][_a-zA-Z0-9]*?)[(](.*?)[)]( -> ([a-zA-Z0-9]+))?")
     res = reg.search(text)
-    name, params, result = res.groups(0)
+    if res is None:
+        return None
+    name, params, _, result = res.groups()
     spl = [_.strip() for _ in params.split(",")]
-    sig = Signature(name.strip(), result.strip())
+    sig = Signature(name.strip(), result.strip() if result is not None else None)
     for p in spl:
-        k, v = p.split(":", maxsplit=1)
-        sig.append(Parameter(k.strip(), v.strip()))
+        if ":" in p:
+            k, v = p.split(":", maxsplit=1)
+            sig.append(Parameter(k.strip(), v.strip()))
+        else:
+            sig.append(Parameter(p.strip(), None))
     return sig
 
-    print(params, result)
-
 
 def check_typed_make_field(
     self,
@@ -110,13 +122,25 @@ def check_item(fieldarg, content, logger):
         "local function"
         if fieldarg not in check_params:
             if function_name is not None:
-                logger.warning(
-                    "[docassert] %r has no parameter %r (in %r)%s.",
-                    function_name,
-                    fieldarg,
-                    docname,
-                    " (no detected signature) " if parameters is None else "",
+                idocname = (
+                    docname.replace(".PyCapsule.", ".")
+                    if ".PyCapsule." in docname
+                    else docname
                 )
+                if kind is None:
+                    obj = import_any_object(idocname)
+                else:
+                    obj = import_object(idocname, kind=kind)
+                tsig = getattr(obj[0], "__text_signature__")
+                if tsig != "($self, /, *args, **kwargs)":
+                    logger.warning(
+                        "[docassert] %r has no parameter %r (in %r) [sig=%r]%s.",
+                        function_name,
+                        fieldarg,
+                        docname,
+                        tsig,
+                        " (no detected signature) " if parameters is None else "",
+                    )
         else:
             check_params[fieldarg] += 1
             if check_params[fieldarg] > 1:
@@ -139,12 +163,42 @@ def check_item(fieldarg, content, logger):
                     # Behavior should be improved.
                     pass
                 else:
-                    logger.warning(
-                        "[docassert] %r has undocumented parameters %r (in %r).",
-                        function_name,
-                        ", ".join(nodoc),
-                        docname,
+                    idocname = (
+                        docname.replace(".PyCapsule.", ".")
+                        if ".PyCapsule." in docname
+                        else docname
                     )
+                    if kind is None:
+                        obj = import_any_object(idocname)
+                    else:
+                        obj = import_object(idocname, kind=kind)
+                    tsig = getattr(obj[0], "__text_signature__", None)
+                    if tsig != "($self, /, *args, **kwargs)":
+                        if tsig is None:
+                            alt_sig = parse_signature(obj[0].__doc__)
+                            if alt_sig is None:
+                                nodoc2 = nodoc
+                            else:
+                                ps = alt_sig.param_names
+                                nodoc2 = [n for n in nodoc if n not in ps]
+                            if len(nodoc2) > 0:
+                                logger.warning(
+                                    "[docassert] %r has undocumented parameters (1) "
+                                    "[%s] (in %r) [sig=%r].",
+                                    function_name,
+                                    ", ".join(nodoc2),
+                                    docname,
+                                    tsig,
+                                )
+                        else:
+                            logger.warning(
+                                "[docassert] %r has undocumented parameters (2) "
+                                "[%s] (in %r) [sig=%r].",
+                                function_name,
+                                ", ".join(nodoc),
+                                docname,
+                                tsig,
+                            )
     else:
         # Documentation related to the return.
         pass
@@ -278,7 +332,6 @@ def override_transform(self, other_self, node):
                     docs,
                     reasons,
                 )
-                myfunc = None
 
             if myfunc is None:
                 signature = None
@@ -290,9 +343,18 @@ def override_transform(self, other_self, node):
                 except (TypeError, ValueError):
                     # built-in function
                     logger = logging.getLogger("docassert")
-                    logger.warning("[docassert] unable to get signature of %r", docs)
-                    signature = None
-                    parameters = None
+                    if myfunc.__text_signature__:
+                        logger.warning(
+                            "[docassert] unable to get signature (1) of %r: %s",
+                            docs,
+                            myfunc.__text_signature__,
+                        )
+                        signature = None
+                        parameters = None
+                    else:
+                        alt_sig = parse_signature(myfunc.__doc__)
+                        signature = alt_sig
+                        parameters = alt_sig.params
 
             # grouped entries need to be collected in one entry, while others
             # get one entry per field
diff --git a/sphinx_runpython/import_object_helper.py b/sphinx_runpython/import_object_helper.py
@@ -62,6 +62,9 @@ def import_object(docname, kind, use_init=True) -> Tuple[object, str]:
             not inspect.isfunction(myfunc)
             and "built-in function" not in str(myfunc)
             and "built-in method" not in str(myfunc)
+            and (
+                not hasattr(myfunc, "func_code") or ".pyx" not in str(myfunc.func_code)
+            )
         ):
             # inspect.isfunction fails for C functions.
             raise TypeError(f"'{docname}' is not a function")
