fix: Invert input/output context if a Python function is called from C++

When the Callable itself is an input (parameter) to a C++ function, its
arguments are outputs (C++ passes them to the Python callback), and vice
versa.
Therefore, we must invert them if C++ calls a Python function, but keep
them the same in the other direction.

Author: ximion

include/pybind11/detail/descr.h

@@ -222,5 +222,10 @@ constexpr descr<N + 4, Ts...> return_descr(const descr<N, Ts...> &descr) {
     return const_name("@$") + descr + const_name("@!");
 }
 
+template <size_t N, typename... Ts>
+constexpr descr<N + 4, Ts...> inv_descr(const descr<N, Ts...> &descr) {
+    return const_name("@~") + descr + const_name("@!");
+}
+
 PYBIND11_NAMESPACE_END(detail)
 PYBIND11_NAMESPACE_END(PYBIND11_NAMESPACE)

include/pybind11/functional.h

@@ -138,9 +138,8 @@ struct type_caster<std::function<Return(Args...)>> {
     PYBIND11_TYPE_CASTER(
         type,
         const_name("collections.abc.Callable[[")
-            + ::pybind11::detail::concat(::pybind11::detail::arg_descr(make_caster<Args>::name)...)
-            + const_name("], ") + ::pybind11::detail::return_descr(make_caster<retval_type>::name)
-            + const_name("]"));
+            + ::pybind11::detail::concat(::pybind11::detail::inv_descr(make_caster<Args>::name)...)
+            + const_name("], ") + make_caster<retval_type>::name + const_name("]"));
 };
 
 PYBIND11_NAMESPACE_END(detail)

include/pybind11/pybind11.h

@@ -185,7 +185,8 @@ inline std::string generate_function_signature(const char *type_caster_name_fiel
             signature += *++pc;
         } else if (c == '@') {
             // `@^ ... @!` and `@$ ... @!` are used to force arg/return value type (see
-            // typing::Callable/detail::arg_descr/detail::return_descr)
+            // typing::Callable/detail::arg_descr/detail::return_descr).
+            // `@~ ... @!` inverts the current context (see detail::inv_descr).
             if (*(pc + 1) == '^') {
                 is_return_value.emplace(false);
                 ++pc;
@@ -196,6 +197,11 @@ inline std::string generate_function_signature(const char *type_caster_name_fiel
                 ++pc;
                 continue;
             }
+            if (*(pc + 1) == '~') {
+                is_return_value.emplace(!is_return_value.top());
+                ++pc;
+                continue;
+            }
             if (*(pc + 1) == '!') {
                 is_return_value.pop();
                 ++pc;