Add an API isinstance(inst, cls) that mirrors the Python isinstance. (#…

…805)

The current `isinstance<T>(inst)` tests if a Python object is an
instance of a bound C++ class. This new overload tests if a Python
object is an instance of a Python class. I have needed this helper in
several nanobind-using codebases, and the same API exists in pybind11.

docs/api_core.rst

@@ -635,6 +635,10 @@ Type queries
    to convert the object to C++. It may be more efficient to just perform the
    conversion using :cpp:func:`cast` and catch potential raised exceptions.
 
+.. cpp:function:: isinstance(handle inst, handle cls)
+
+   Checks if the Python object `inst` is an instance of the Python type `cls`.
+
 .. cpp:function:: template <typename T> handle type() noexcept
 
    Returns the Python type object associated with the C++ type `T`. When the

docs/changelog.rst

@@ -49,6 +49,10 @@ Version TBD (unreleased)
   Previously, after ``a += b``, ``a`` would be replaced with a copy.
   (PR `#803 <https://github.com/wjakob/nanobind/pull/803>`__)
 
+- Added an overload to :cpp:func:`isinstance` which tests if a Python object
+  is an instance of a Python class. This is in addition to the existing
+  overload, which tests if a Python object is an instance of a bound C++ class.
+
 - Added support for overriding static properties, such as those defined using
   ``def_prop_ro_static``, in subclasses. Previously this would fail with an
   error.

include/nanobind/nb_misc.h

@@ -111,6 +111,13 @@ inline Py_hash_t hash(handle h) {
     return rv;
 }
 
+inline bool isinstance(handle inst, handle cls) {
+    int ret = PyObject_IsInstance(inst.ptr(), cls.ptr());
+    if (ret == -1)
+      nanobind::raise_python_error();
+    return ret;
+}
+
 inline bool is_alive() noexcept {
     return detail::is_alive();
 }

tests/test_functions.cpp

@@ -440,6 +440,9 @@ NB_MODULE(test_functions_ext, m) {
     });
 
     m.def("hash_it", [](nb::handle h) { return nb::hash(h); });
+    m.def("isinstance_", [](nb::handle inst, nb::handle cls) {
+        return nb::isinstance(inst, cls);
+    });
 
     // Test bytearray type
     m.def("test_bytearray_new",     []() { return nb::bytearray(); });

tests/test_functions.py

@@ -725,3 +725,9 @@ def case(arg1, arg2, expect_ret):  # type: (str, str, str | None) -> str
         case("swapfrom", "xxx", "<unfinished>")
     with pytest.raises(RuntimeError, match="offset too large"):
         case("swapfrom", "10", "<unfinished>")
+
+def test51_isinstance():
+    assert t.isinstance_(3, int)
+    assert not t.isinstance_(3, bool)
+    with pytest.raises(TypeError):
+        t.isinstance_(3, 7)