feat(types): add support for typing.Literal type

include/pybind11/typing.h

@@ -70,14 +70,31 @@ class Type : public type {
 
 template <typename... Types>
 class Union : public object {
+    PYBIND11_OBJECT_DEFAULT(Union, object, PyObject_Type)
     using object::object;
 };
 
 template <typename T>
 class Optional : public object {
+    PYBIND11_OBJECT_DEFAULT(Optional, object, PyObject_Type)
     using object::object;
 };
 
+#if defined(__cpp_nontype_template_parameter_class)
+template <size_t N>
+struct StringLiteral {
+    constexpr StringLiteral(const char (&str)[N]) { std::copy_n(str, N, name); }
+    char name[N];
+};
+
+// NOTE: C++ implemented constant template Literal[1, 2] does not equal Literal[2, 1]
+template <StringLiteral... StrLits>
+class Literal : public object {
+    PYBIND11_OBJECT_DEFAULT(Literal, object, PyObject_Type)
+    using object::object;
+};
+#endif
+
 PYBIND11_NAMESPACE_END(typing)
 
 PYBIND11_NAMESPACE_BEGIN(detail)
@@ -153,5 +170,14 @@ struct handle_type_name<typing::Optional<T>> {
     static constexpr auto name = const_name("Optional[") + make_caster<T>::name + const_name("]");
 };
 
+#if defined(__cpp_nontype_template_parameter_class)
+template <typing::StringLiteral... Literals>
+struct handle_type_name<typing::Literal<Literals...>> {
+    static constexpr auto name = const_name("Literal[")
+                                 + pybind11::detail::concat(const_name(Literals.name)...)
+                                 + const_name("]");
+};
+#endif
+
 PYBIND11_NAMESPACE_END(detail)
 PYBIND11_NAMESPACE_END(PYBIND11_NAMESPACE)

tests/test_pytypes.cpp

@@ -109,6 +109,22 @@ void m_defs(py::module_ &m) {
 
 } // namespace handle_from_move_only_type_with_operator_PyObject
 
+namespace literals {
+#if defined(__cpp_nontype_template_parameter_class)
+enum Color { RED = 0, BLUE = 1 };
+
+typedef py::typing::Literal<"26",
+                            "0x1A",
+                            "\"hello world\"",
+                            "b\"hello world\"",
+                            "u\"hello world\"",
+                            "True",
+                            "Color.RED",
+                            "None">
+    LiteralFoo;
+#endif
+} // namespace literals
+
 TEST_SUBMODULE(pytypes, m) {
     m.def("obj_class_name", [](py::handle obj) { return py::detail::obj_class_name(obj.ptr()); });
 
@@ -844,7 +860,8 @@ TEST_SUBMODULE(pytypes, m) {
     m.def("annotate_iterator_int", [](const py::typing::Iterator<int> &) {});
     m.def("annotate_fn",
           [](const py::typing::Callable<int(py::typing::List<py::str>, py::str)> &) {});
-    m.def("annotate_type", [](const py::typing::Type<int> &) {});
+
+    m.def("annotate_type", [](const py::typing::Type<int> &t) -> py::type { return t; });
 
     m.def("annotate_union",
           [](py::typing::List<py::typing::Union<py::str, py::int_, py::object>> l,
@@ -861,10 +878,26 @@ TEST_SUBMODULE(pytypes, m) {
           [](py::typing::List<py::typing::Union<py::str>> &l)
               -> py::typing::List<py::typing::Union<py::int_>> { return l; });
 
+    m.def("annotate_union_to_object",
+          [](py::typing::Union<int, py::str> &o) -> py::object { return o; });
+
     m.def("annotate_optional",
           [](py::list &list) -> py::typing::List<py::typing::Optional<py::str>> {
               list.append(py::str("hi"));
               list.append(py::none());
               return list;
           });
+    m.def("annotate_optional_to_object",
+          [](py::typing::Optional<int> &o) -> py::object { return o; });
+
+#if defined(__cpp_nontype_template_parameter_class)
+    py::enum_<literals::Color>(m, "Color")
+        .value("RED", literals::Color::RED)
+        .value("BLUE", literals::Color::BLUE);
+
+    m.def("annotate_literal", [](literals::LiteralFoo &o) -> py::object { return o; });
+    m.attr("if_defined__cpp_nontype_template_parameter_class") = true;
+#else
+    m.attr("if_defined__cpp_nontype_template_parameter_class") = false;
+#endif
 }

tests/test_pytypes.py

@@ -960,7 +960,7 @@ def test_fn_annotations(doc):
 
 
 def test_type_annotation(doc):
-    assert doc(m.annotate_type) == "annotate_type(arg0: type[int]) -> None"
+    assert doc(m.annotate_type) == "annotate_type(arg0: type[int]) -> type"
 
 
 def test_union_annotations(doc):
@@ -977,8 +977,33 @@ def test_union_typing_only(doc):
     )
 
 
+def test_union_object_annotations(doc):
+    assert (
+        doc(m.annotate_union_to_object)
+        == "annotate_union_to_object(arg0: Union[int, str]) -> object"
+    )
+
+
 def test_optional_annotations(doc):
     assert (
         doc(m.annotate_optional)
         == "annotate_optional(arg0: list) -> list[Optional[str]]"
     )
+
+
+def test_optional_object_annotations(doc):
+    assert (
+        doc(m.annotate_optional_to_object)
+        == "annotate_optional_to_object(arg0: Optional[int]) -> object"
+    )
+
+
+@pytest.mark.skipif(
+    not m.if_defined__cpp_nontype_template_parameter_class,
+    reason="C++20 feature not available.",
+)
+def test_literal(doc):
+    assert (
+        doc(m.annotate_literal)
+        == 'annotate_literal(arg0: Literal[26, 0x1A, "hello world", b"hello world", u"hello world", True, Color.RED, None]) -> object'
+    )