Added option for different arg/return type hints to type_caster

include/pybind11/pybind11.h

@@ -101,6 +101,30 @@ inline std::string replace_newlines_and_squash(const char *text) {
 #    define PYBIND11_COMPAT_STRDUP strdup
 #endif
 
+/// Type trait checker for `descr`.
+template <typename>
+struct is_descr : std::false_type {};
+
+template <size_t N, typename... Ts>
+struct is_descr<descr<N, Ts...>> : std::true_type {};
+
+template <size_t N, typename... Ts>
+struct is_descr<const descr<N, Ts...>> : std::true_type {};
+
+/// Checks for `return_name` in `type_caster` to replace `name` for return type hints.
+/// this is useful for having a different python type hint for args vs return value,
+/// e.g., `std::filesystem::path` -> Arg: `Union[os.PathLike, str, bytes]`, return: `Path`.
+template <typename T, typename Enable = void>
+struct as_return_type {
+    static constexpr auto name = T::name;
+};
+
+template <typename T>
+struct as_return_type<T,
+                      typename std::enable_if<is_descr<decltype(T::return_name)>::value>::type> {
+    static constexpr auto name = T::return_name;
+};
+
 PYBIND11_NAMESPACE_END(detail)
 
 /// Wraps an arbitrary C++ function/method/lambda function/.. into a callable Python object
@@ -319,8 +343,8 @@ class cpp_function : public function {
 
         /* Generate a readable signature describing the function's arguments and return
            value types */
-        static constexpr auto signature
-            = const_name("(") + cast_in::arg_names + const_name(") -> ") + cast_out::name;
+        static constexpr auto signature = const_name("(") + cast_in::arg_names
+                                          + const_name(") -> ") + as_return_type<cast_out>::name;
         PYBIND11_DESCR_CONSTEXPR auto types = decltype(signature)::types();
 
         /* Register the function with Python from generic (non-templated) code */

include/pybind11/stl/filesystem.h

@@ -106,7 +106,8 @@ struct path_caster {
         return true;
     }
 
-    PYBIND11_TYPE_CASTER(T, const_name("os.PathLike"));
+    PYBIND11_TYPE_CASTER(T, const_name("Union[os.PathLike, str, bytes]"));
+    static constexpr auto return_name = const_name("Path");
 };
 
 #endif // PYBIND11_HAS_FILESYSTEM || defined(PYBIND11_HAS_EXPERIMENTAL_FILESYSTEM)

tests/test_stl.cpp

@@ -454,6 +454,13 @@ TEST_SUBMODULE(stl, m) {
     // test_fs_path
     m.attr("has_filesystem") = true;
     m.def("parent_path", [](const std::filesystem::path &p) { return p.parent_path(); });
+    m.def("parent_paths", [](const std::vector<std::filesystem::path> &p) {
+        std::vector<std::filesystem::path> result;
+        for (const auto &i : p) {
+            result.push_back(i.parent_path());
+        }
+        return result;
+    });
 #endif
 
 #ifdef PYBIND11_TEST_VARIANT

tests/test_stl.py

@@ -245,7 +245,7 @@ def test_reference_sensitive_optional():
 
 
 @pytest.mark.skipif(not hasattr(m, "has_filesystem"), reason="no <filesystem>")
-def test_fs_path():
+def test_fs_path(doc):
     from pathlib import Path
 
     class PseudoStrPath:
@@ -261,6 +261,15 @@ def __fspath__(self):
     assert m.parent_path(b"foo/bar") == Path("foo")
     assert m.parent_path(PseudoStrPath()) == Path("foo")
     assert m.parent_path(PseudoBytesPath()) == Path("foo")
+    assert (
+        doc(m.parent_path)
+        == "parent_path(arg0: Union[os.PathLike, str, bytes]) -> Path"
+    )
+    assert m.parent_paths(["foo/bar", "foo/baz"]) == [Path("foo"), Path("foo")]
+    assert (
+        doc(m.parent_paths)
+        == "parent_paths(arg0: list[Union[os.PathLike, str, bytes]]) -> list[Path]"
+    )
 
 
 @pytest.mark.skipif(not hasattr(m, "load_variant"), reason="no <variant>")