fix comparison table API scraping (#530)

Author: bryevdv

cupynumeric/_sphinxext/_comparison_config.py

@@ -83,12 +83,11 @@ class SectionConfig:
 UFUNCS = (numpy.ufunc,)
 
 NUMPY_CONFIGS = [
-    SectionConfig("Module-Level", None, types=FUNCTIONS),
-    SectionConfig("Ufuncs", None, types=UFUNCS),
-    SectionConfig("Multi-Dimensional Array", "ndarray", types=METHODS),
-    SectionConfig("Linear Algebra", "linalg", types=FUNCTIONS),
-    SectionConfig("Discrete Fourier Transform", "fft", types=FUNCTIONS),
-    SectionConfig("Random Sampling", "random", types=FUNCTIONS),
+    SectionConfig("Module-Level", None),
+    SectionConfig("Multi-Dimensional Array", "ndarray"),
+    SectionConfig("Linear Algebra", "linalg"),
+    SectionConfig("Discrete Fourier Transform", "fft"),
+    SectionConfig("Random Sampling", "random"),
 ]
 
 CONVOLVE = ("convolve", "correlate")

cupynumeric/_sphinxext/_comparison_util.py

@@ -16,9 +16,9 @@
 
 from dataclasses import dataclass
 from types import ModuleType
-from typing import TYPE_CHECKING, Any, Iterable, Iterator, Type
+from typing import TYPE_CHECKING, Any, Iterable, Iterator
 
-from .._utils.coverage import is_implemented, is_multi, is_single
+from .._utils.coverage import is_implemented, is_multi, is_single, is_wrapped
 from ._comparison_config import MISSING_NP_REFS, SKIP
 
 if TYPE_CHECKING:
@@ -73,17 +73,31 @@ def _lgref(name: str, obj: Any, implemented: bool) -> str:
     return f":{role}:`{full_name}`"
 
 
-def filter_names(
+def filter_wrapped_names(
     obj: Any,
-    types: tuple[Type[Any], ...] | None = None,
+    *,
     skip: Iterable[str] = (),
 ) -> Iterator[str]:
     names = (n for n in dir(obj))  # every name in the module or class
+    names = (
+        n for n in names if is_wrapped(getattr(obj, n))
+    )  # that is wrapped
+    names = (n for n in names if n not in skip)  # except the ones we skip
+    names = (n for n in names if not n.startswith("_"))  # or any private names
+    return names
+
+
+def filter_type_names(
+    obj: Any,
+    *,
+    skip: Iterable[str] = (),
+) -> Iterator[str]:
+    names = (n for n in dir(obj))  # every name in the module or class
+    names = (
+        n for n in names if isinstance(getattr(obj, n), type)
+    )  # that is a type (class, dtype, etc)
     names = (n for n in names if n not in skip)  # except the ones we skip
     names = (n for n in names if not n.startswith("_"))  # or any private names
-    if types:
-        # optionally filtered by type
-        names = (n for n in names if isinstance(getattr(obj, n), types))
     return names
 
 
@@ -123,9 +137,14 @@ def generate_section(config: SectionConfig) -> SectionDetail:
     names: Iterable[str]
 
     if config.names:
-        names = config.names
+        names = set(config.names)
     else:
-        names = filter_names(np_obj, config.types, skip=SKIP)
+        wrapped_names = filter_wrapped_names(lg_obj, skip=SKIP)
+        type_names = filter_type_names(lg_obj, skip=SKIP)
+        names = set(wrapped_names) | set(type_names)
+
+    # we can omit anything that isn't in np namespace to begin with
+    names = {n for n in names if n in dir(np_obj)}
 
     items = [get_item(name, np_obj, lg_obj) for name in names]
 

cupynumeric/_utils/coverage.py

@@ -17,7 +17,7 @@
 import warnings
 from dataclasses import dataclass
 from functools import WRAPPER_ASSIGNMENTS, wraps
-from types import BuiltinFunctionType, FunctionType, ModuleType
+from types import BuiltinFunctionType, ModuleType
 from typing import Any, Callable, Container, Iterable, Mapping, Protocol, cast
 
 from legate.core import track_provenance
@@ -69,7 +69,7 @@ class CuWrapperMetadata:
 
 
 class CuWrapped(AnyCallable, Protocol):
-    _cupynumeric: CuWrapperMetadata
+    _cupynumeric_metadata: CuWrapperMetadata
     __wrapped__: AnyCallable
     __name__: str
     __qualname__: str
@@ -116,7 +116,7 @@ def wrapper(*args: Any, **kwargs: Any) -> Any:
     multi = "Multiple GPUs" in (getattr(func, "__doc__", None) or "")
     single = "Single GPU" in (getattr(func, "__doc__", None) or "") or multi
 
-    wrapper._cupynumeric = CuWrapperMetadata(
+    wrapper._cupynumeric_metadata = CuWrapperMetadata(
         implemented=True, single=single, multi=multi
     )
 
@@ -185,7 +185,7 @@ def wrapper(*args: Any, **kwargs: Any) -> Any:
     --------
     {name}
     """
-    wrapper._cupynumeric = CuWrapperMetadata(implemented=False)
+    wrapper._cupynumeric_metadata = CuWrapperMetadata(implemented=False)
 
     return wrapper
 
@@ -242,7 +242,7 @@ def clone_module(
         # Only need to wrap things that are in the origin module to begin with
         if attr not in origin_module.__dict__:
             continue
-        if isinstance(value, (FunctionType, lgufunc)) or (
+        if should_wrap(value) or (
             include_builtin_function_type
             and isinstance(value, BuiltinFunctionType)
         ):
@@ -273,7 +273,7 @@ def clone_module(
     from numpy import ufunc as npufunc
 
     for attr, value in missing.items():
-        if isinstance(value, (FunctionType, npufunc)) or (
+        if should_wrap(value) or (
             include_builtin_function_type
             and isinstance(value, BuiltinFunctionType)
         ):
@@ -300,13 +300,19 @@ def clone_module(
 
 
 def should_wrap(obj: object) -> bool:
-    # custom callables, e.g. cython used in np2, do not inherit anything. See
-    # https://github.com/nv-legate/cupynumeric.internal/issues/179#issuecomment-2423813051
+    from numpy import ufunc as npufunc
+
+    from .._ufunc.ufunc import ufunc as lgufunc
+
+    # Custom callables, e.g. cython functions used in np2, do not inherit
+    # anything, so we check callable() instead (and include the __get__/__set__
+    # checks to filter out classes). OTOH ufuncs need to be checked specially
+    # because they do not have __get__.
     return (
         callable(obj)
         and hasattr(obj, "__get__")
         and not hasattr(obj, "__set__")
-    )
+    ) or isinstance(obj, (lgufunc, npufunc))
 
 
 def clone_class(
@@ -363,13 +369,17 @@ def _clone_class(cls: type) -> type:
     return _clone_class
 
 
+def is_wrapped(obj: Any) -> bool:
+    return hasattr(obj, "_cupynumeric_metadata")
+
+
 def is_implemented(obj: Any) -> bool:
-    return hasattr(obj, "_cupynumeric") and obj._cupynumeric.implemented
+    return is_wrapped(obj) and obj._cupynumeric_metadata.implemented
 
 
 def is_single(obj: Any) -> bool:
-    return hasattr(obj, "_cupynumeric") and obj._cupynumeric.single
+    return is_wrapped(obj) and obj._cupynumeric_metadata.single
 
 
 def is_multi(obj: Any) -> bool:
-    return hasattr(obj, "_cupynumeric") and obj._cupynumeric.multi
+    return is_wrapped(obj) and obj._cupynumeric_metadata.multi

tests/integration/test_array_fallback.py

@@ -27,7 +27,7 @@ def test_unimplemented_method_self_fallback():
     # to verify a behaviour of unimplemented ndarray method wrappers. If std
     # becomes implemeneted in the future, this assertion will start to fail,
     # and a new (unimplemented) ndarray method should be found to replace it
-    assert not ones.std._cupynumeric.implemented
+    assert not ones.std._cupynumeric_metadata.implemented
 
     ones.std()
 

tests/integration/test_fallback.py

@@ -33,7 +33,7 @@ def test_ufunc():
     # methods. If logical_and.accumulate becomes implemented in the future,
     # this assertion will start to fail, and a new (unimplemented) ufunc method
     # should be found to replace it
-    assert not num.logical_and.accumulate._cupynumeric.implemented
+    assert not num.logical_and.accumulate._cupynumeric_metadata.implemented
 
     out_num = num.logical_and.accumulate(in_num)
     out_np = np.logical_and.accumulate(in_np)

tests/unit/cupynumeric/_sphinxext/test__comparison_util.py

@@ -35,26 +35,31 @@ def test_get_namespaces_attr(attr):
     assert res[1] is getattr(num, attr)
 
 
+class _wrapped:
+    class _cupynumeric_metadata:
+        implemeneted = True
+
+
 class _TestObj:
-    a = 10
-    b = 10.2
-    c = "str"
-    _priv = "priv"
+    a = _wrapped
+    b = _wrapped
+    c = _wrapped
+    d = 10
+    _priv = _wrapped
 
 
-class Test_filter_names:
+class Test_filter_wrapped_names:
     def test_default(self):
-        assert set(m.filter_names(_TestObj)) == {"a", "b", "c"}
-
-    def test_types(self):
-        assert set(m.filter_names(_TestObj, (int,))) == {"a"}
-        assert set(m.filter_names(_TestObj, (int, str))) == {"a", "c"}
-        assert set(m.filter_names(_TestObj, (int, set))) == {"a"}
-        assert set(m.filter_names(_TestObj, (set,))) == set()
+        assert set(m.filter_wrapped_names(_TestObj())) == {"a", "b", "c"}
 
     def test_skip(self):
-        assert set(m.filter_names(_TestObj, skip=("a",))) == {"b", "c"}
-        assert set(m.filter_names(_TestObj, skip=("a", "c"))) == {"b"}
+        assert set(m.filter_wrapped_names(_TestObj(), skip=("a",))) == {
+            "b",
+            "c",
+        }
+        assert set(m.filter_wrapped_names(_TestObj(), skip=("a", "c"))) == {
+            "b"
+        }
 
 
 if __name__ == "__main__":

tests/unit/cupynumeric/_utils/test_coverage.py

@@ -117,6 +117,23 @@ def __call__(self, a: int, b: int) -> int:
 _test_ufunc = _Test_ufunc()
 
 
+class Test_helpers:
+    def test_is_wrapped_true(self) -> None:
+        wrapped = m.implemented(_test_func, "foo", "_test_func")
+        assert m.is_wrapped(wrapped)
+
+    def test_is_wrapped_false(self) -> None:
+        assert not m.is_wrapped(10)
+
+    def test_is_implemented_true(self) -> None:
+        wrapped = m.implemented(_test_func, "foo", "_test_func")
+        assert m.is_implemented(wrapped)
+
+    def test_is_implemented_false(self) -> None:
+        wrapped = m.unimplemented(_test_func, "foo", "_test_func")
+        assert not m.is_implemented(wrapped)
+
+
 class Test_implemented:
     @patch("cupynumeric.runtime.record_api_call")
     def test_reporting_True_func(
@@ -347,10 +364,10 @@ def test_report_coverage_True(self) -> None:
         assert _Dest.attr2 == 30
 
         assert _Dest.function1.__wrapped__ is _OriginMod.function1
-        assert not _Dest.function1._cupynumeric.implemented
+        assert not _Dest.function1._cupynumeric_metadata.implemented
 
         assert _Dest.function2.__wrapped__
-        assert _Dest.function2._cupynumeric.implemented
+        assert _Dest.function2._cupynumeric_metadata.implemented
 
         assert not hasattr(_Dest.extra, "_cupynumeric")
 
@@ -373,10 +390,10 @@ def test_report_coverage_False(self) -> None:
         assert _Dest.attr2 == 30
 
         assert _Dest.function1.__wrapped__ is _OriginMod.function1
-        assert not _Dest.function1._cupynumeric.implemented
+        assert not _Dest.function1._cupynumeric_metadata.implemented
 
         assert _Dest.function2.__wrapped__
-        assert _Dest.function2._cupynumeric.implemented
+        assert _Dest.function2._cupynumeric_metadata.implemented
 
         assert not hasattr(_Dest.extra, "_cupynumeric")
 
@@ -428,10 +445,10 @@ def test_report_coverage_True(self) -> None:
         assert _Test_ndarray.attr2 == 30
 
         assert _Test_ndarray.foo.__wrapped__ is _Orig_ndarray.foo
-        assert not _Test_ndarray.foo._cupynumeric.implemented
+        assert not _Test_ndarray.foo._cupynumeric_metadata.implemented
 
         assert _Test_ndarray.bar.__wrapped__
-        assert _Test_ndarray.bar._cupynumeric.implemented
+        assert _Test_ndarray.bar._cupynumeric_metadata.implemented
 
         assert not hasattr(_Test_ndarray.extra, "_cupynumeric")
 
@@ -447,10 +464,10 @@ def test_report_coverage_False(self) -> None:
         assert _Test_ndarray.attr2 == 30
 
         assert _Test_ndarray.foo.__wrapped__ is _Orig_ndarray.foo
-        assert not _Test_ndarray.foo._cupynumeric.implemented
+        assert not _Test_ndarray.foo._cupynumeric_metadata.implemented
 
         assert _Test_ndarray.bar.__wrapped__
-        assert _Test_ndarray.bar._cupynumeric.implemented
+        assert _Test_ndarray.bar._cupynumeric_metadata.implemented
 
         assert not hasattr(_Test_ndarray.extra, "_cupynumeric")
 
@@ -469,32 +486,32 @@ def test_ufunc_methods_binary() -> None:
 
     # reduce is implemented
     assert np.add.reduce.__wrapped__
-    assert np.add.reduce._cupynumeric.implemented
+    assert np.add.reduce._cupynumeric_metadata.implemented
 
     # the rest are not
     assert np.add.reduceat.__wrapped__
-    assert not np.add.reduceat._cupynumeric.implemented
+    assert not np.add.reduceat._cupynumeric_metadata.implemented
     assert np.add.outer.__wrapped__
-    assert not np.add.outer._cupynumeric.implemented
+    assert not np.add.outer._cupynumeric_metadata.implemented
     assert np.add.at.__wrapped__
-    assert not np.add.at._cupynumeric.implemented
+    assert not np.add.at._cupynumeric_metadata.implemented
     assert np.add.accumulate.__wrapped__
-    assert not np.add.accumulate._cupynumeric.implemented
+    assert not np.add.accumulate._cupynumeric_metadata.implemented
 
 
 def test_ufunc_methods_unary() -> None:
     import cupynumeric as np
 
     assert np.negative.reduce.__wrapped__
-    assert not np.negative.reduce._cupynumeric.implemented
+    assert not np.negative.reduce._cupynumeric_metadata.implemented
     assert np.negative.reduceat.__wrapped__
-    assert not np.negative.reduceat._cupynumeric.implemented
+    assert not np.negative.reduceat._cupynumeric_metadata.implemented
     assert np.negative.outer.__wrapped__
-    assert not np.negative.outer._cupynumeric.implemented
+    assert not np.negative.outer._cupynumeric_metadata.implemented
     assert np.negative.at.__wrapped__
-    assert not np.negative.at._cupynumeric.implemented
+    assert not np.negative.at._cupynumeric_metadata.implemented
     assert np.negative.accumulate.__wrapped__
-    assert not np.negative.accumulate._cupynumeric.implemented
+    assert not np.negative.accumulate._cupynumeric_metadata.implemented
 
 
 if __name__ == "__main__":