Added option for different arg/return type hints to type_caster

[timohl]

Description

This PR adds the option for defining return_name in a custom type_caster, which allows to have different python type hints for arguments and return value. The check if return_name is available or name should be used as fallback is implemented using the template class as_return_type.

This is entirely optional and should not impact any existing type_caster. One exception is the type_caster for std::filesystem::path, which was modified to support this new feature. Here, Union[os.PathLike, str, bytes] is the argument type hint and Path is the return type hint. This is more accurate than the previous usage of os.PathLike for both argument and return type hint. I have updated the unit test to check for the new signature.

Suggested changelog entry:

Added option for different arg/return type hints to type_caster.
Updated stl/filesystem to use correct arg/return type hints.

Possible TODOs

• [ ] Update Custom type casters documentation
• [x] Test if it works in containers like list[Path] -> does not work
• [ ] Fix for all handle_type_name (maybe some recursive template magic adding as_return_type to subtypes)
• [ ] Update type hints for Eigen (currently uses np.ndarray as arg type hint but also takes lists and tuples (should probably be numpy.typing.ArrayLike + maybe typing.Annotated for shape/dtype annotation

I would love to get feedback on this! Especially on the "Possible TODO" regarding Eigen. Should I implement that here in this PR or should I open a separate PR later?

Currently I am working on adding typing stubs to Open3D (isl-org/Open3D#6917) using pybind11-stubgen. Applying mypy/pyright on existing example code showed that a lot of type checks failed, which could be fixed by this PR.

[timohl]

The new unit test in 7d16bad shows that it does not work for nested types, e.g., list[Path]. This requires to somehow inject as_return_type into all handle_type_name subtypes. Maybe some recursive template magic could be possible.

Going to pull back as a draft and try to work on that.