Add type_caster<std::monostate> (pybind#3818)

* Add type_caster<std::monostate> for std::variant

Add type_caster<std::monostate>, allowing std::variant<std::monostate, ...>

* Add  variant<std::monostate, ...> test methods

* Add std::monostate tests

* Update test_stl.py

Remove erroneous extra tests

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Update test fn name

* And update the doc() test

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

include/pybind11/stl.h

@@ -406,6 +406,9 @@ struct variant_caster<V<Ts...>> {
 #if defined(PYBIND11_HAS_VARIANT)
 template <typename... Ts>
 struct type_caster<std::variant<Ts...>> : variant_caster<std::variant<Ts...>> {};
+
+template <>
+struct type_caster<std::monostate> : public void_caster<std::monostate> {};
 #endif
 
 PYBIND11_NAMESPACE_END(detail)

tests/test_stl.cpp

@@ -37,9 +37,10 @@ struct type_caster<boost::none_t> : void_caster<boost::none_t> {};
 // Test with `std::variant` in C++17 mode, or with `boost::variant` in C++11/14
 #if defined(PYBIND11_HAS_VARIANT)
 using std::variant;
+#    define PYBIND11_TEST_VARIANT 1
 #elif defined(PYBIND11_TEST_BOOST)
 #    include <boost/variant.hpp>
-#    define PYBIND11_HAS_VARIANT 1
+#    define PYBIND11_TEST_VARIANT 1
 using boost::variant;
 
 namespace pybind11 {
@@ -424,7 +425,7 @@ TEST_SUBMODULE(stl, m) {
     m.def("parent_path", [](const std::filesystem::path &p) { return p.parent_path(); });
 #endif
 
-#ifdef PYBIND11_HAS_VARIANT
+#ifdef PYBIND11_TEST_VARIANT
     static_assert(std::is_same<py::detail::variant_caster_visitor::result_type, py::handle>::value,
                   "visitor::result_type is required by boost::variant in C++11 mode");
 
@@ -435,6 +436,9 @@ TEST_SUBMODULE(stl, m) {
         result_type operator()(const std::string &) { return "std::string"; }
         result_type operator()(double) { return "double"; }
         result_type operator()(std::nullptr_t) { return "std::nullptr_t"; }
+#    if defined(PYBIND11_HAS_VARIANT)
+        result_type operator()(std::monostate) { return "std::monostate"; }
+#    endif
     };
 
     // test_variant
@@ -448,6 +452,18 @@ TEST_SUBMODULE(stl, m) {
         using V = variant<int, std::string>;
         return py::make_tuple(V(5), V("Hello"));
     });
+
+#    if defined(PYBIND11_HAS_VARIANT)
+    // std::monostate tests.
+    m.def("load_monostate_variant",
+          [](const variant<std::monostate, int, std::string> &v) -> const char * {
+              return py::detail::visit_helper<variant>::call(visitor(), v);
+          });
+    m.def("cast_monostate_variant", []() {
+        using V = variant<std::monostate, int, std::string>;
+        return py::make_tuple(V{}, V(5), V("Hello"));
+    });
+#    endif
 #endif
 
     // #528: templated constructor

tests/test_stl.py

@@ -263,6 +263,22 @@ def test_variant(doc):
     )
 
 
+@pytest.mark.skipif(
+    not hasattr(m, "load_monostate_variant"), reason="no std::monostate"
+)
+def test_variant_monostate(doc):
+    assert m.load_monostate_variant(None) == "std::monostate"
+    assert m.load_monostate_variant(1) == "int"
+    assert m.load_monostate_variant("1") == "std::string"
+
+    assert m.cast_monostate_variant() == (None, 5, "Hello")
+
+    assert (
+        doc(m.load_monostate_variant)
+        == "load_monostate_variant(arg0: Union[None, int, str]) -> str"
+    )
+
+
 def test_vec_of_reference_wrapper():
     """#171: Can't return reference wrappers (or STL structures containing them)"""
     assert (