allow passing a 'return value policy' to handle::operator()

docs/advanced.rst

@@ -461,7 +461,9 @@ functions. The default policy is :enum:`return_value_policy::automatic`.
 |                                                  | See below for a description of what all of these different policies do.    |
 +--------------------------------------------------+----------------------------------------------------------------------------+
 | :enum:`return_value_policy::automatic_reference` | As above, but use policy :enum:`return_value_policy::reference` when the   |
-|                                                  | return value is a pointer. You probably won't need to use this.            |
+|                                                  | return value is a pointer. This is the default conversion policy for       |
+|                                                  | function arguments when calling Python functions manually from C++ code    |
+|                                                  | (i.e. via handle::operator()). You probably won't need to use this.        |
 +--------------------------------------------------+----------------------------------------------------------------------------+
 | :enum:`return_value_policy::take_ownership`      | Reference an existing object (i.e. do not create a new copy) and take      |
 |                                                  | ownership. Python will call the destructor and delete operator when the    |

include/pybind11/cast.h

@@ -842,16 +842,18 @@ template <return_value_policy policy = return_value_policy::automatic_reference,
     return result;
 }
 
-template <typename... Args> object handle::operator()(Args&&... args) const {
-    tuple args_tuple = pybind11::make_tuple(std::forward<Args>(args)...);
+template <return_value_policy policy,
+          typename... Args> object handle::operator()(Args&&... args) const {
+    tuple args_tuple = pybind11::make_tuple<policy>(std::forward<Args>(args)...);
     object result(PyObject_CallObject(m_ptr, args_tuple.ptr()), false);
     if (!result)
         throw error_already_set();
     return result;
 }
 
-template <typename... Args> object handle::call(Args &&... args) const {
-    return operator()(std::forward<Args>(args)...);
+template <return_value_policy policy,
+          typename... Args> object handle::call(Args &&... args) const {
+    return operator()<policy>(std::forward<Args>(args)...);
 }
 
 inline object handle::operator()(detail::args_proxy args) const {

include/pybind11/common.h

@@ -151,7 +151,9 @@ enum class return_value_policy : uint8_t {
     automatic = 0,
 
     /** As above, but use policy return_value_policy::reference when the return
-        value is a pointer. You probably won't need to use this. */
+        value is a pointer. This is the default conversion policy for function
+        arguments when calling Python functions manually from C++ code (i.e. via
+        handle::operator()). You probably won't need to use this. */
     automatic_reference,
 
     /** Reference an existing object (i.e. do not create a new copy) and take

include/pybind11/pytypes.h

@@ -39,12 +39,13 @@ public:
     inline detail::accessor attr(const char *key) const;
     inline pybind11::str str() const;
     template <typename T> T cast() const;
-    template <typename ... Args>
+    template <return_value_policy policy = return_value_policy::automatic_reference, typename ... Args>
     #if __cplusplus > 201103L
     [[deprecated("call(...) was deprecated in favor of operator()(...)")]]
     #endif
     object call(Args&&... args) const;
-    template <typename ... Args> object operator()(Args&&... args) const;
+    template <return_value_policy policy = return_value_policy::automatic_reference, typename ... Args>
+    object operator()(Args&&... args) const;
     inline object operator()(detail::args_proxy args) const;
     inline object operator()(detail::args_proxy f_args, detail::kwargs_proxy kwargs) const;
     operator bool() const { return m_ptr != nullptr; }