Custom handle name of *args and **kwargs in function signature in docstrings

[XuehaiPan]

For the most use cases, we use py::arg("name") to explicitly define the argument name in the binding code:

m.def("func", &func, py::arg("a"), py::arg("b"))

which binds a Python function:

def func(a, b):
    ...

In Functions: Accepting *args and **kwargs:

void generic(py::args args, const py::kwargs& kwargs) {
    ...
}

/// Binding code
m.def("generic", &generic);

The code binds a python function:

def generic(*args, **kwargs):
    ...  # do something with args and kwargs

However, py::args do not allow the user defines a custom name of the *args argument. For example, the following code:

mod.def(
    "func",
    [](const py::object& a,
        const py::object& b,
        const py::args& pos_args,
        const py::object& c) { return py::make_tuple(a, b, pos_args, c); },
    "Some function descriptions.",
    py::arg("a"),
    py::arg("b"),
    py::arg("c"),
);

binds a Python function:

def func(a, b, *pos_args, c):
    return (a, b, pos_args, c)

while in Python REPL:

>>> import mod
>>> print(mod.func.__doc__)
func(a: object, b: object, *args, c: object) -> tuple

Some function descriptions.

the *pos_args handle appears as *args in the function signature.

The handle name of py::args and py::kwargs are hardcoded and are not customizable:

pybind11/include/pybind11/cast.h

Lines 900 to 907 in 7c6f2f8

	template <>
	struct handle_type_name<args> {
	static constexpr auto name = const_name("*args");
	};
	template <>
	struct handle_type_name<kwargs> {
	static constexpr auto name = const_name("**kwargs");
	};