From f40ffc026244cdc56138d868042130b6b5aacc75 Mon Sep 17 00:00:00 2001
From: "Ralf W. Grosse-Kunstleve" <rgrossekunst@nvidia.com>
Date: Sat, 12 Oct 2024 11:35:23 -0700
Subject: [PATCH] `type_caster_incomplete_type` sketch

---
 tests/CMakeLists.txt                       |  1 +
 tests/test_type_caster_incomplete_type.cpp | 49 ++++++++++++++++++++++
 tests/test_type_caster_incomplete_type.py  | 11 +++++
 3 files changed, 61 insertions(+)
 create mode 100644 tests/test_type_caster_incomplete_type.cpp
 create mode 100644 tests/test_type_caster_incomplete_type.py

diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
index 03ff39138..b3ccda3d8 100644
--- a/tests/CMakeLists.txt
+++ b/tests/CMakeLists.txt
@@ -149,6 +149,7 @@ set(PYBIND11_TEST_FILES
     test_stl_binders
     test_tagbased_polymorphic
     test_thread
+    test_type_caster_incomplete_type
     test_type_caster_pyobject_ptr
     test_type_caster_std_function_specializations
     test_union
diff --git a/tests/test_type_caster_incomplete_type.cpp b/tests/test_type_caster_incomplete_type.cpp
new file mode 100644
index 000000000..dd51890d8
--- /dev/null
+++ b/tests/test_type_caster_incomplete_type.cpp
@@ -0,0 +1,49 @@
+#include "pybind11_tests.h"
+
+namespace test_type_caster_incomplete_type {
+
+struct ForwardDeclaredType {};
+
+} // namespace test_type_caster_incomplete_type
+
+using ForwardDeclaredType = test_type_caster_incomplete_type::ForwardDeclaredType;
+
+// TODO: Move to pybind11/type_caster_incomplete_type.h, wrap in a macro.
+namespace pybind11 {
+namespace detail {
+
+template <>
+class type_caster<ForwardDeclaredType> {
+public:
+    static constexpr auto name = const_name("object");
+
+    static handle cast(ForwardDeclaredType * /*src*/,
+                       return_value_policy /*policy*/,
+                       handle /*parent*/) {
+        return py::none().release(); // TODO: Build and return capsule with src pointer;
+    }
+
+    bool load(handle /*src*/, bool /*convert*/) {
+        // TODO: Assign pointer_capsule = src after inspecting src.
+        return true;
+    }
+
+    template <typename T>
+    using cast_op_type = ForwardDeclaredType *;
+
+    explicit operator ForwardDeclaredType *() {
+        return nullptr; // TODO: Retrieve C++ pointer from pointer_capsule.
+    }
+
+private:
+    capsule pointer_capsule;
+};
+
+} // namespace detail
+} // namespace pybind11
+
+TEST_SUBMODULE(type_caster_incomplete_type, m) {
+    m.def("rtrn_fwd_decl_type_ptr",
+          []() { return reinterpret_cast<ForwardDeclaredType *>(0); });
+    m.def("pass_fwd_decl_type_ptr", [](ForwardDeclaredType *) {});
+}
diff --git a/tests/test_type_caster_incomplete_type.py b/tests/test_type_caster_incomplete_type.py
new file mode 100644
index 000000000..1dcef1a72
--- /dev/null
+++ b/tests/test_type_caster_incomplete_type.py
@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from pybind11_tests import type_caster_incomplete_type as m
+
+
+def test_rtrn_fwd_decl_type_ptr():
+    assert m.rtrn_fwd_decl_type_ptr() is None
+
+
+def test_pass_fwd_decl_type_ptr():
+    assert m.pass_fwd_decl_type_ptr(None) is None