pytypes: Add iterable_t<>

Author: EricCousineau-TRI

include/pybind11/cast.h

@@ -50,6 +50,18 @@ PYBIND11_NAMESPACE_BEGIN(detail)
 template <typename type, typename SFINAE = void> class type_caster : public type_caster_base<type> { };
 template <typename type> using make_caster = type_caster<intrinsic_t<type>>;
 
+template <typename T>
+struct is_generic_type<
+    T,
+    enable_if_t<std::is_base_of<type_caster_generic, make_caster<T>>::value>
+    > : public std::true_type {};
+
+template <typename T>
+struct is_generic_type<
+    T,
+    enable_if_t<!std::is_base_of<type_caster_generic, make_caster<T>>::value>
+    > : public std::false_type {};
+
 // Shortcut for calling a caster's `cast_op_type` cast operator for casting a type_caster to a T
 template <typename T> typename make_caster<T>::template cast_op_type<T> cast_op(make_caster<T> &caster) {
     return caster.operator typename make_caster<T>::template cast_op_type<T>();
@@ -747,11 +759,16 @@ template <typename T> struct handle_type_name { static constexpr auto name = _<T
 template <> struct handle_type_name<bytes> { static constexpr auto name = _(PYBIND11_BYTES_NAME); };
 template <> struct handle_type_name<int_> { static constexpr auto name = _("int"); };
 template <> struct handle_type_name<iterable> { static constexpr auto name = _("Iterable"); };
+template <typename T>
+struct handle_type_name<iterable_t<T>> {
+    static constexpr auto name = _("Iterable[") + type_caster<T>::name + _("]");
+};
 template <> struct handle_type_name<iterator> { static constexpr auto name = _("Iterator"); };
 template <> struct handle_type_name<none> { static constexpr auto name = _("None"); };
 template <> struct handle_type_name<args> { static constexpr auto name = _("*args"); };
 template <> struct handle_type_name<kwargs> { static constexpr auto name = _("**kwargs"); };
 
+
 template <typename type>
 struct pyobject_caster {
     template <typename T = type, enable_if_t<std::is_same<T, handle>::value, int> = 0>

include/pybind11/pytypes.h

@@ -26,6 +26,11 @@ PYBIND11_NAMESPACE_BEGIN(detail)
 class args_proxy;
 inline bool isinstance_generic(handle obj, const std::type_info &tp);
 
+// Indicates that type is generic and and does not have a specialized
+// `type_caster<>` specialization. Defined in `cast.h`.
+template <typename T, typename SFINAE = void>
+struct is_generic_type;
+
 // Accessor forward declarations
 template <typename Policy> class accessor;
 namespace accessor_policies {
@@ -380,13 +385,18 @@ class error_already_set : public std::runtime_error {
 /** \ingroup python_builtins
     \rst
     Return true if ``obj`` is an instance of ``T``. Type ``T`` must be a subclass of
-    `object` or a class which was exposed to Python as ``py::class_<T>``.
+    `object` or a class which was exposed to Python as ``py::class_<T>`` (generic).
 \endrst */
 template <typename T, detail::enable_if_t<std::is_base_of<object, T>::value, int> = 0>
 bool isinstance(handle obj) { return T::check_(obj); }
 
 template <typename T, detail::enable_if_t<!std::is_base_of<object, T>::value, int> = 0>
-bool isinstance(handle obj) { return detail::isinstance_generic(obj, typeid(T)); }
+bool isinstance(handle obj) {
+    static_assert(
+        detail::is_generic_type<T>::value,
+        "isisntance<T>() requires specialization for this type");
+    return detail::isinstance_generic(obj, typeid(T));
+}
 
 template <> inline bool isinstance<handle>(handle) = delete;
 template <> inline bool isinstance<object>(handle obj) { return obj.ptr() != nullptr; }
@@ -753,6 +763,39 @@ inline bool PyIterable_Check(PyObject *obj) {
     }
 }
 
+template <typename T>
+bool PyIterableT_Check(PyObject *obj) {
+    static_assert(
+        is_generic_type<T>::value || is_pyobject<T>::value,
+        "iterable_t can only be used with pyobjects and generic types "
+        "(py::class_<T>)");
+    PyObject *iter = PyObject_GetIter(obj);
+    if (iter) {
+        if (iter == obj) {
+            // If they are the same, then that's bad! For now, just throw a
+            // cast error.
+            Py_DECREF(iter);
+            throw cast_error(
+                "iterable_t<T> cannot be used with exhausitble iterables "
+                "(e.g., iterators, generators).");
+        }
+        bool good = true;
+        // Now that we know that the iterable `obj` will not be exhausted,
+        // let's check the contained types.
+        for (handle h : handle(iter)) {
+            if (!isinstance<T>(h)) {
+                good = false;
+                break;
+            }
+        }
+        Py_DECREF(iter);
+        return good;
+    } else {
+        PyErr_Clear();
+        return false;
+    }
+}
+
 inline bool PyNone_Check(PyObject *o) { return o == Py_None; }
 inline bool PyEllipsis_Check(PyObject *o) { return o == Py_Ellipsis; }
 
@@ -941,6 +984,20 @@ class iterable : public object {
     PYBIND11_OBJECT_DEFAULT(iterable, object, detail::PyIterable_Check)
 };
 
+/// Provides similar interface to `iterable`, but constraining the intended
+/// type.
+/// @warning Due to technical reasons, this is constrained in two ways:
+/// - Due to how `isinstance<T>()` works, this does *not* work for iterables of
+///   type-converted values (e.g. `int`).
+/// - Because we must check the contained types within the iterable (for
+///   overloads), we must iterate through the iterable. For this reason, the
+///   iterable should *not* be exhaustible (e.g., iterator, generator).
+template <typename T>
+class iterable_t : public iterable {
+public:
+    PYBIND11_OBJECT_DEFAULT(iterable_t, iterable, detail::PyIterableT_Check<T>)
+};
+
 class bytes;
 
 class str : public object {

tests/test_pytypes.cpp

@@ -17,6 +17,14 @@ TEST_SUBMODULE(pytypes, m) {
     m.def("get_iterator", []{return py::iterator();});
     // test_iterable
     m.def("get_iterable", []{return py::iterable();});
+    // test_iterable_t
+    m.def("get_iterable_t", []{return py::iterable_t<py::str>();});
+    // test_iterable_t_overloads
+    m.def("accept_iterable_t", [](py::iterable_t<py::str>) { return "str"; });
+    m.def("accept_iterable_t", [](py::iterable_t<py::bytes>) { return "bytes"; });
+    // // Uncomment to see compiler error.
+    // m.def("accept_iterable_t", [](py::iterable_t<int>) { return "int"; });
+
     // test_list
     m.def("get_list", []() {
         py::list list;

tests/test_pytypes.py

@@ -21,6 +21,45 @@ def test_iterable(doc):
     assert doc(m.get_iterable) == "get_iterable() -> Iterable"
 
 
+def test_iterable_t(doc):
+    assert doc(m.get_iterable_t) == "get_iterable_t() -> Iterable[str]"
+
+
+def test_iterable_t_overloads():
+    # Empty: First one wins.
+    list_empty = []
+    set_empty = set()
+    assert m.accept_iterable_t(list_empty) == "str"
+    assert m.accept_iterable_t(set_empty) == "str"
+    # Negative: Exhaustible iterables (e.g. iterators, generators).
+    gen_empty = (x for x in set_empty)
+    with pytest.raises(RuntimeError):
+        m.accept_iterable_t(gen_empty)
+    iter_empty = iter(list_empty)
+    with pytest.raises(RuntimeError):
+        m.accept_iterable_t(iter_empty)
+
+    # Str.
+    list_of_str = ["hey", "you"]
+    set_of_str = {"hey", "you"}
+    assert m.accept_iterable_t(list_of_str) == "str"
+    assert m.accept_iterable_t(set_of_str) == "str"
+    # - Negative: Not fully `str`.
+    list_of_str_and_then_some = ["hey", 0]
+    with pytest.raises(TypeError):
+        m.accept_iterable_t(list_of_str_and_then_some)
+
+    # Bytes.
+    list_of_bytes = [b"hey", b"you"]
+    set_of_bytes = {b"hey", b"you"}
+    assert m.accept_iterable_t(list_of_bytes) == "bytes"
+    assert m.accept_iterable_t(set_of_bytes) == "bytes"
+    # - Negative: Not fully `bytes`.
+    list_of_bytes_and_then_some = [b"hey", 0]
+    with pytest.raises(TypeError):
+        m.accept_iterable_t(list_of_bytes_and_then_some)
+
+
 def test_list(capture, doc):
     with capture:
         lst = m.get_list()