Option for arg/return type hints and correct typing for std::filesystem::path (#5450)

* Added arg/return type handling.

* Added support for nested arg/return type in py::typing::List

* Added support for arg/return type in stl/filesystem

* Added tests for arg/return type in stl/filesystem and py::typing::List

* Added arg/return name to more py::typing classes

* Added arg/return type to Callable[...]

* Added tests for typing container classes (also nested)

* Changed typing classes to avoid using C++14 auto return type deduction.

* Fixed clang-tidy errors.

* Changed Enable to SFINAE

* Added test for Tuple[T, ...]

* Added RealNumber with custom caster for testing typing classes.

* Added tests for Set, Iterable, Iterator, Union, and Optional

* Added tests for Callable

* Fixed Callable with ellipsis test

* Changed TypeGuard/TypeIs to use return type (being the narrower type) + Tests

* Added test for use of fallback type name with stl vector

* Updated documentation.

* Fixed unnecessary constructor call in test.

* Fixed reference counting in example type caster.

* Fixed clang-tidy issues.

* Fix for clang-tidy

* Updated cast method to use pybind11 API rather than Python C API in custom caster example

* Updated load to use pybind11 API rather than Python C API in custom caster example

* Changed test of arg/return name to use pybind11 API instead of Python C API

* Updated code in adcanced/cast example and improved documentation text

* Fixed references in custom type caster docs

* Fixed wrong logical and operator in test

* Fixed wrong logical operator in doc example

* Added comment to test about `float` vs `float | int`

* Updated std::filesystem::path docs in cast/overview section

* Remove one stray dot.

---------

Co-authored-by: Ralf W. Grosse-Kunstleve <rgrossekunst@nvidia.com>

tests/test_stl.py

@@ -246,7 +246,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:
@@ -257,11 +257,59 @@ def test_fs_path():
         def __fspath__(self):
             return b"foo/bar"
 
+    # Single argument
     assert m.parent_path(Path("foo/bar")) == Path("foo")
     assert m.parent_path("foo/bar") == Path("foo")
     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"
+    )
+    # std::vector should use name (for arg_name/return_name typing classes must be used)
+    assert m.parent_paths(["foo/bar", "foo/baz"]) == [Path("foo"), Path("foo")]
+    assert (
+        doc(m.parent_paths)
+        == "parent_paths(arg0: list[os.PathLike]) -> list[os.PathLike]"
+    )
+    # py::typing::List
+    assert m.parent_paths_list(["foo/bar", "foo/baz"]) == [Path("foo"), Path("foo")]
+    assert (
+        doc(m.parent_paths_list)
+        == "parent_paths_list(arg0: list[Union[os.PathLike, str, bytes]]) -> list[Path]"
+    )
+    # Nested py::typing::List
+    assert m.parent_paths_nested_list([["foo/bar"], ["foo/baz", "foo/buzz"]]) == [
+        [Path("foo")],
+        [Path("foo"), Path("foo")],
+    ]
+    assert (
+        doc(m.parent_paths_nested_list)
+        == "parent_paths_nested_list(arg0: list[list[Union[os.PathLike, str, bytes]]]) -> list[list[Path]]"
+    )
+    # py::typing::Tuple
+    assert m.parent_paths_tuple(("foo/bar", "foo/baz")) == (Path("foo"), Path("foo"))
+    assert (
+        doc(m.parent_paths_tuple)
+        == "parent_paths_tuple(arg0: tuple[Union[os.PathLike, str, bytes], Union[os.PathLike, str, bytes]]) -> tuple[Path, Path]"
+    )
+    # py::typing::Dict
+    assert m.parent_paths_dict(
+        {
+            "key1": Path("foo/bar"),
+            "key2": "foo/baz",
+            "key3": b"foo/buzz",
+        }
+    ) == {
+        "key1": Path("foo"),
+        "key2": Path("foo"),
+        "key3": Path("foo"),
+    }
+    assert (
+        doc(m.parent_paths_dict)
+        == "parent_paths_dict(arg0: dict[str, Union[os.PathLike, str, bytes]]) -> dict[str, Path]"
+    )
 
 
 @pytest.mark.skipif(not hasattr(m, "load_variant"), reason="no <variant>")