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.cpp

@@ -16,6 +16,7 @@
 #    define PYBIND11_HAS_FILESYSTEM_IS_OPTIONAL
 #endif
 #include <pybind11/stl/filesystem.h>
+#include <pybind11/typing.h>
 
 #include <string>
 #include <vector>
@@ -453,7 +454,57 @@ TEST_SUBMODULE(stl, m) {
 #ifdef PYBIND11_HAS_FILESYSTEM
     // test_fs_path
     m.attr("has_filesystem") = true;
-    m.def("parent_path", [](const std::filesystem::path &p) { return p.parent_path(); });
+    m.def("parent_path", [](const std::filesystem::path &path) { return path.parent_path(); });
+    m.def("parent_paths", [](const std::vector<std::filesystem::path> &paths) {
+        std::vector<std::filesystem::path> result;
+        result.reserve(paths.size());
+        for (const auto &path : paths) {
+            result.push_back(path.parent_path());
+        }
+        return result;
+    });
+    m.def("parent_paths_list", [](const py::typing::List<std::filesystem::path> &paths) {
+        py::typing::List<std::filesystem::path> result;
+        for (auto path : paths) {
+            result.append(path.cast<std::filesystem::path>().parent_path());
+        }
+        return result;
+    });
+    m.def("parent_paths_nested_list",
+          [](const py::typing::List<py::typing::List<std::filesystem::path>> &paths_lists) {
+              py::typing::List<py::typing::List<std::filesystem::path>> result_lists;
+              for (auto paths : paths_lists) {
+                  py::typing::List<std::filesystem::path> result;
+                  for (auto path : paths) {
+                      result.append(path.cast<std::filesystem::path>().parent_path());
+                  }
+                  result_lists.append(result);
+              }
+              return result_lists;
+          });
+    m.def("parent_paths_tuple",
+          [](const py::typing::Tuple<std::filesystem::path, std::filesystem::path> &paths) {
+              py::typing::Tuple<std::filesystem::path, std::filesystem::path> result
+                  = py::make_tuple(paths[0].cast<std::filesystem::path>().parent_path(),
+                                   paths[1].cast<std::filesystem::path>().parent_path());
+              return result;
+          });
+    m.def("parent_paths_tuple_ellipsis",
+          [](const py::typing::Tuple<std::filesystem::path, py::ellipsis> &paths) {
+              py::typing::Tuple<std::filesystem::path, py::ellipsis> result(paths.size());
+              for (size_t i = 0; i < paths.size(); ++i) {
+                  result[i] = paths[i].cast<std::filesystem::path>().parent_path();
+              }
+              return result;
+          });
+    m.def("parent_paths_dict",
+          [](const py::typing::Dict<std::string, std::filesystem::path> &paths) {
+              py::typing::Dict<std::string, std::filesystem::path> result;
+              for (auto it : paths) {
+                  result[it.first] = it.second.cast<std::filesystem::path>().parent_path();
+              }
+              return result;
+          });
 #endif
 
 #ifdef PYBIND11_TEST_VARIANT