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

[ximion]

Hi!

Description

In my project, I have a type ByteVector with a type-caster defined like this:
PYBIND11_TYPE_CASTER(ByteVector, io_name("bytes | bytearray", "bytes"));
So, we accept any bytes or bytearray to turn into a ByteVector, but when passing it to Python, it's always bytes (because Python can't modify the vector, which is alright in this case).

API users pass in Python functions as callbacks that are called on specific events that the C++ interface processes. This currently leads to type annotations that look like this:

@property
def on_save_settings(self) -> collections.abc.Callable[[os.PathLike | str | bytes], bytes]:
    ...
@on_save_settings.setter
def on_save_settings(self, arg1: collections.abc.Callable[[os.PathLike | str | bytes], bytes]) -> None:
    ...

The function return type is only bytes even though it is input to C++ and therefore should accept both byte-like types. Similar things apply for the path.

Currently, pybind11 expects Python to call C++ functions when receiving a callback, not the opposite.
This patch fixes the type annotations by inverting them if Python passes in a function into C++, and leaving them the same in the other direction. This leads to type annotations that look like this:

@property
def on_save_settings(self) -> collections.abc.Callable[[os.PathLike | str | bytes], bytes]:
    ...
@on_save_settings.setter
def on_save_settings(self, arg1: collections.abc.Callable[[pathlib.Path], bytes | bytearray]) -> None:
    ...

Now, if you pass in a function Python -> C++, its i/o context is inverted, as it will be called from C++. However, in the other direction (receiving one from C++) everything stays the same as before.

I think this is probably the best we can do to address both cases automatically in pybind11, or do you have a better solution to this problem?

Thank you for making pybind11, it's an incredibly helpful project!

Suggested changelog entry:

• Invert the input/output context if a Python function is called from C++