feat(types): Use typing.SupportsInt and typing.SupportsFloat

include/pybind11/cast.h

@@ -22,6 +22,7 @@
 #include <iosfwd>
 #include <iterator>
 #include <memory>
+#include <stack>
 #include <string>
 #include <tuple>
 #include <type_traits>
@@ -241,7 +242,9 @@ struct type_caster<T, enable_if_t<std::is_arithmetic<T>::value && !is_std_char_t
         return PyLong_FromUnsignedLongLong((unsigned long long) src);
     }
 
-    PYBIND11_TYPE_CASTER(T, const_name<std::is_integral<T>::value>("int", "float"));
+    PYBIND11_TYPE_CASTER(T,
+                         io_name<std::is_integral<T>::value>(
+                             "typing.SupportsInt", "int", "typing.SupportsFloat", "float"));
 };
 
 template <typename T>
@@ -952,7 +955,7 @@ struct handle_type_name<buffer> {
 };
 template <>
 struct handle_type_name<int_> {
-    static constexpr auto name = const_name("int");
+    static constexpr auto name = io_name("typing.SupportsInt", "int");
 };
 template <>
 struct handle_type_name<iterable> {
@@ -964,7 +967,7 @@ struct handle_type_name<iterator> {
 };
 template <>
 struct handle_type_name<float_> {
-    static constexpr auto name = const_name("float");
+    static constexpr auto name = io_name("typing.SupportsFloat", "float");
 };
 template <>
 struct handle_type_name<function> {
@@ -1345,7 +1348,73 @@ str_attr_accessor object_api<D>::attr_with_type_hint(const char *key) const {
     if (ann.contains(key)) {
         throw std::runtime_error("__annotations__[\"" + std::string(key) + "\"] was set already.");
     }
-    ann[key] = make_caster<T>::name.text;
+
+    const char *text = make_caster<T>::name.text;
+
+    std::string signature;
+    // `is_return_value.top()` is true if we are currently inside the return type of the
+    // signature. Using `@^`/`@$` we can force types to be arg/return types while `@!` pops
+    // back to the previous state.
+    std::stack<bool> is_return_value({false});
+    // The following characters have special meaning in the signature parsing. Literals
+    // containing these are escaped with `!`.
+    std::string special_chars("!@%{}-");
+
+    // Simplified version of similar parser in cpp_function
+    for (const auto *pc = text; *pc != '\0'; ++pc) {
+        const auto c = *pc;
+        if (c == '!' && special_chars.find(*(pc + 1)) != std::string::npos) {
+            // typing::Literal escapes special characters with !
+            signature += *++pc;
+        } else if (c == '@') {
+            // `@^ ... @!` and `@$ ... @!` are used to force arg/return value type (see
+            // typing::Callable/detail::arg_descr/detail::return_descr)
+            if (*(pc + 1) == '^') {
+                is_return_value.emplace(false);
+                ++pc;
+                continue;
+            }
+            if (*(pc + 1) == '$') {
+                is_return_value.emplace(true);
+                ++pc;
+                continue;
+            }
+            if (*(pc + 1) == '!') {
+                is_return_value.pop();
+                ++pc;
+                continue;
+            }
+            // Handle types that differ depending on whether they appear
+            // in an argument or a return value position (see io_name<text1, text2>).
+            // For named arguments (py::arg()) with noconvert set, return value type is used.
+            ++pc;
+            if (!is_return_value.top()) {
+                while (*pc != '\0' && *pc != '@') {
+                    signature += *pc++;
+                }
+                if (*pc == '@') {
+                    ++pc;
+                }
+                while (*pc != '\0' && *pc != '@') {
+                    ++pc;
+                }
+            } else {
+                while (*pc != '\0' && *pc != '@') {
+                    ++pc;
+                }
+                if (*pc == '@') {
+                    ++pc;
+                }
+                while (*pc != '\0' && *pc != '@') {
+                    signature += *pc++;
+                }
+            }
+        } else {
+            signature += c;
+        }
+    }
+
+    ann[key] = signature;
     return {derived(), key};
 }
 

include/pybind11/detail/descr.h

@@ -106,6 +106,18 @@ constexpr descr<N1 + N2 + 1> io_name(char const (&text1)[N1], char const (&text2
            + const_name("@");
 }
 
+template <bool B, size_t N1, size_t N2, size_t N3, size_t N4>
+constexpr enable_if_t<B, descr<N1 + N2 + 1>>
+io_name(char const (&text1)[N1], char const (&text2)[N2], char const (&)[N3], char const (&)[N4]) {
+    return io_name(text1, text2);
+}
+
+template <bool B, size_t N1, size_t N2, size_t N3, size_t N4>
+constexpr enable_if_t<!B, descr<N3 + N4 + 1>>
+io_name(char const (&)[N1], char const (&)[N2], char const (&text3)[N3], char const (&text4)[N4]) {
+    return io_name(text3, text4);
+}
+
 // If "_" is defined as a macro, py::detail::_ cannot be provided.
 // It is therefore best to use py::detail::const_name universally.
 // This block is for backward compatibility only.

include/pybind11/pybind11.h

@@ -450,7 +450,6 @@ class cpp_function : public function {
         std::string special_chars("!@%{}-");
         for (const auto *pc = text; *pc != '\0'; ++pc) {
             const auto c = *pc;
-
             if (c == '{') {
                 // Write arg name for everything except *args and **kwargs.
                 is_starred = *(pc + 1) == '*';

include/pybind11/typing.h

@@ -228,7 +228,9 @@ struct handle_type_name<typing::Optional<T>> {
 
 template <typename T>
 struct handle_type_name<typing::Final<T>> {
-    static constexpr auto name = const_name("Final[") + make_caster<T>::name + const_name("]");
+    static constexpr auto name = const_name("Final[")
+                                 + ::pybind11::detail::return_descr(make_caster<T>::name)
+                                 + const_name("]");
 };
 
 template <typename T>

tests/test_builtin_casters.cpp

@@ -236,6 +236,10 @@ TEST_SUBMODULE(builtin_casters, m) {
     m.def("int_passthrough", [](int arg) { return arg; });
     m.def("int_passthrough_noconvert", [](int arg) { return arg; }, py::arg{}.noconvert());
 
+    // test_float_convert
+    m.def("float_passthrough", [](float arg) { return arg; });
+    m.def("float_passthrough_noconvert", [](float arg) { return arg; }, py::arg{}.noconvert());
+
     // test_tuple
     m.def(
         "pair_passthrough",

tests/test_builtin_casters.py

@@ -247,7 +247,7 @@ def test_integer_casting():
     assert "incompatible function arguments" in str(excinfo.value)
 
 
-def test_int_convert():
+def test_int_convert(doc):
     class Int:
         def __int__(self):
             return 42
@@ -286,6 +286,9 @@ def __int__(self):
 
     convert, noconvert = m.int_passthrough, m.int_passthrough_noconvert
 
+    assert doc(convert) == "int_passthrough(arg0: typing.SupportsInt) -> int"
+    assert doc(noconvert) == "int_passthrough_noconvert(arg0: int) -> int"
+
     def requires_conversion(v):
         pytest.raises(TypeError, noconvert, v)
 
@@ -318,6 +321,22 @@ def cant_convert(v):
     requires_conversion(RaisingValueErrorOnIndex())
 
 
+def test_float_convert(doc):
+    class Float:
+        def __float__(self):
+            return 41.45
+
+    convert, noconvert = m.float_passthrough, m.float_passthrough_noconvert
+    assert doc(convert) == "float_passthrough(arg0: typing.SupportsFloat) -> float"
+    assert doc(noconvert) == "float_passthrough_noconvert(arg0: float) -> float"
+
+    def requires_conversion(v):
+        pytest.raises(TypeError, noconvert, v)
+
+    requires_conversion(Float())
+    assert pytest.approx(convert(Float())) == 41.45
+
+
 def test_numpy_int_convert():
     np = pytest.importorskip("numpy")
 
@@ -362,7 +381,7 @@ def test_tuple(doc):
     assert (
         doc(m.tuple_passthrough)
         == """
-        tuple_passthrough(arg0: tuple[bool, str, int]) -> tuple[int, str, bool]
+        tuple_passthrough(arg0: tuple[bool, str, typing.SupportsInt]) -> tuple[int, str, bool]
 
         Return a triple in reversed order
     """

tests/test_callbacks.py

@@ -138,7 +138,10 @@ def test_cpp_function_roundtrip():
 
 
 def test_function_signatures(doc):
-    assert doc(m.test_callback3) == "test_callback3(arg0: Callable[[int], int]) -> str"
+    assert (
+        doc(m.test_callback3)
+        == "test_callback3(arg0: Callable[[typing.SupportsInt], typing.SupportsInt]) -> str"
+    )
     assert doc(m.test_callback4) == "test_callback4() -> Callable[[int], int]"
 
 

tests/test_class.py

@@ -145,13 +145,13 @@ def test_qualname(doc):
     assert (
         doc(m.NestBase.Nested.fn)
         == """
-        fn(self: m.class_.NestBase.Nested, arg0: int, arg1: m.class_.NestBase, arg2: m.class_.NestBase.Nested) -> None
+        fn(self: m.class_.NestBase.Nested, arg0: typing.SupportsInt, arg1: m.class_.NestBase, arg2: m.class_.NestBase.Nested) -> None
     """
     )
     assert (
         doc(m.NestBase.Nested.fa)
         == """
-        fa(self: m.class_.NestBase.Nested, a: int, b: m.class_.NestBase, c: m.class_.NestBase.Nested) -> None
+        fa(self: m.class_.NestBase.Nested, a: typing.SupportsInt, b: m.class_.NestBase, c: m.class_.NestBase.Nested) -> None
     """
     )
     assert m.NestBase.__module__ == "pybind11_tests.class_"

tests/test_custom_type_casters.py

@@ -75,7 +75,7 @@ def test_noconvert_args(msg):
         msg(excinfo.value)
         == """
         ints_preferred(): incompatible function arguments. The following argument types are supported:
-            1. (i: int) -> int
+            1. (i: typing.SupportsInt) -> int
 
         Invoked with: 4.0
     """

tests/test_docstring_options.py

@@ -19,9 +19,13 @@ def test_docstring_options():
     assert m.test_overloaded3.__doc__ == "Overload docstr"
 
     # options.enable_function_signatures()
-    assert m.test_function3.__doc__.startswith("test_function3(a: int, b: int) -> None")
+    assert m.test_function3.__doc__.startswith(
+        "test_function3(a: typing.SupportsInt, b: typing.SupportsInt) -> None"
+    )
 
-    assert m.test_function4.__doc__.startswith("test_function4(a: int, b: int) -> None")
+    assert m.test_function4.__doc__.startswith(
+        "test_function4(a: typing.SupportsInt, b: typing.SupportsInt) -> None"
+    )
     assert m.test_function4.__doc__.endswith("A custom docstring\n")
 
     # options.disable_function_signatures()
@@ -32,7 +36,9 @@ def test_docstring_options():
     assert m.test_function6.__doc__ == "A custom docstring"
 
     # RAII destructor
-    assert m.test_function7.__doc__.startswith("test_function7(a: int, b: int) -> None")
+    assert m.test_function7.__doc__.startswith(
+        "test_function7(a: typing.SupportsInt, b: typing.SupportsInt) -> None"
+    )
     assert m.test_function7.__doc__.endswith("A custom docstring\n")
 
     # when all options are disabled, no docstring (instead of an empty one) should be generated

tests/test_factory_constructors.py

@@ -78,10 +78,10 @@ def test_init_factory_signature(msg):
         msg(excinfo.value)
         == """
         __init__(): incompatible constructor arguments. The following argument types are supported:
-            1. m.factory_constructors.TestFactory1(arg0: m.factory_constructors.tag.unique_ptr_tag, arg1: int)
+            1. m.factory_constructors.TestFactory1(arg0: m.factory_constructors.tag.unique_ptr_tag, arg1: typing.SupportsInt)
             2. m.factory_constructors.TestFactory1(arg0: str)
             3. m.factory_constructors.TestFactory1(arg0: m.factory_constructors.tag.pointer_tag)
-            4. m.factory_constructors.TestFactory1(arg0: object, arg1: int, arg2: object)
+            4. m.factory_constructors.TestFactory1(arg0: object, arg1: typing.SupportsInt, arg2: object)
 
         Invoked with: 'invalid', 'constructor', 'arguments'
     """
@@ -93,13 +93,13 @@ def test_init_factory_signature(msg):
         __init__(*args, **kwargs)
         Overloaded function.
 
-        1. __init__(self: m.factory_constructors.TestFactory1, arg0: m.factory_constructors.tag.unique_ptr_tag, arg1: int) -> None
+        1. __init__(self: m.factory_constructors.TestFactory1, arg0: m.factory_constructors.tag.unique_ptr_tag, arg1: typing.SupportsInt) -> None
 
         2. __init__(self: m.factory_constructors.TestFactory1, arg0: str) -> None
 
         3. __init__(self: m.factory_constructors.TestFactory1, arg0: m.factory_constructors.tag.pointer_tag) -> None
 
-        4. __init__(self: m.factory_constructors.TestFactory1, arg0: object, arg1: int, arg2: object) -> None
+        4. __init__(self: m.factory_constructors.TestFactory1, arg0: object, arg1: typing.SupportsInt, arg2: object) -> None
     """
     )