reintroduce vectorcall optimization with new PyCallArgs trait

[Icxolu]

This reintroduces the vectorcall optimization we removed temporarily in #4653 using a new PyCallArgs trait as was discussed during the initial implementation in #4456.

This slightly reduces the number of types that can be passed to PyAnyMethods::call and friends. With this only Rust tuples (including unit), Bound<PyTuple> and Py<PyTuple> are allowed (instead of any type that can be converted into a PyTuple via IntoPyObject as before). Inside pyo3 there is no such type, but there could be user types (for example #[derive(IntoPyObject)] tuple structs) that won't work anymore. The work around is to simply convert at the call site, so I don't think that's a huge blocker.

There are still possibilities left open with regards to kwargs. One idea could be a PyCallArgs type with a builder like API to set both, positional and keyword args which can than be transformed as needed depending on the calling convention (maybe with something like smallvec or even heapless::Vec to avoid lots of small allocation). I might explore that as a followup.

Closes #4656

[Copilot]

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 suggestion.

Comments skipped due to low confidence (1)

src/call.rs:1

• The TODO comment should be replaced with meaningful documentation.

//! TODO

[codspeed-hq]

CodSpeed Performance Report

Merging #4768 will improve performances by 57.92%

_{Comparing Icxolu:pycallargs (ec67980) with main (9e63b34)}

Summary

⚡ 5 improvements
✅ 79 untouched benchmarks

Benchmarks breakdown

	Benchmark	main	Icxolu:pycallargs	Change
⚡	call	756.2 µs	620.5 µs	+21.87%
⚡	call_1	380.1 µs	271 µs	+40.27%
⚡	call_method_1	1,008.9 µs	641.4 µs	+57.29%
⚡	call_method_one_arg	965.8 µs	611.6 µs	+57.92%
⚡	call_one_arg	347.7 µs	242.1 µs	+43.64%

[Icxolu]

Looks like it worked! If we're roughly happy with this, I'll work on the docs.

[Icxolu]

It looks like we can even enable some of it on the limited api after 3.12: https://docs.python.org/3/c-api/call.html#c.PyObject_Vectorcall, but I don't think we have the ffi definitions yet.

[davidhewitt]

Awesome! Always so satisfying to see such big perf wins. 😂

I actually have the FFI bindings in #4379 but I haven't completed splitting that PR up.

[davidhewitt]

I think it's a good idea to have all the methods hidden and the type sealed; we can explain the situation with docs 👍.

Especially if in the long term we might have something like #4414 to solve keyword args (although much design experimentation still needed to make sure we're all happy with whatever we come up with).

[Icxolu]

I took a first pass on the docs, let we know what you think.

[davidhewitt]

I think this looks super, thanks. Sorry for the long delays, I am beginning to pick off the long backlog now 🫣

[Icxolu]

No worries 😄, and happy holidays🎄

[davidhewitt]

Thanks, happy holidays to you too! 🎉 🎄