include/pybind11/typing.h

0001 /*
0002     pybind11/typing.h: Convenience wrapper classes for basic Python types
0003     with more explicit annotations.
0004
0005     Copyright (c) 2023 Dustin Spicuzza <dustin@virtualroadside.com>
0006
0007     All rights reserved. Use of this source code is governed by a
0008     BSD-style license that can be found in the LICENSE file.
0009 */
0010
0011 #pragma once
0012
0013 #include "detail/common.h"
0014 #include "cast.h"
0015 #include "pytypes.h"
0016
0017 #include <algorithm>
0018
0019 #if defined(__cpp_nontype_template_args) && __cpp_nontype_template_args >= 201911L
0020 #    define PYBIND11_TYPING_H_HAS_STRING_LITERAL
0021 #    include <numeric>
0022 #    include <ranges>
0023 #    include <string_view>
0024 #endif
0025
0026 PYBIND11_NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
0027 PYBIND11_NAMESPACE_BEGIN(typing)
0028
0029 /*
0030     The following types can be used to direct pybind11-generated docstrings
0031     to have have more explicit types (e.g., `list[str]` instead of `list`).
0032     Just use these in place of existing types.
0033
0034     There is no additional enforcement of types at runtime.
0035 */
0036
0037 // Tuple type hint defined in cast.h for use in py::make_tuple to avoid circular includes
0038
0039 template <typename K, typename V>
0040 class Dict : public dict {
0041     using dict::dict;
0042 };
0043
0044 template <typename T>
0045 class List : public list {
0046     using list::list;
0047 };
0048
0049 template <typename T>
0050 class Set : public set {
0051     using set::set;
0052 };
0053
0054 template <typename T>
0055 class Iterable : public iterable {
0056     using iterable::iterable;
0057 };
0058
0059 template <typename T>
0060 class Iterator : public iterator {
0061     using iterator::iterator;
0062 };
0063
0064 template <typename Signature>
0065 class Callable;
0066
0067 template <typename Return, typename... Args>
0068 class Callable<Return(Args...)> : public function {
0069     using function::function;
0070 };
0071
0072 template <typename T>
0073 class Type : public type {
0074     using type::type;
0075 };
0076
0077 template <typename... Types>
0078 class Union : public object {
0079     PYBIND11_OBJECT_DEFAULT(Union, object, PyObject_Type)
0080     using object::object;
0081 };
0082
0083 template <typename T>
0084 class Optional : public object {
0085     PYBIND11_OBJECT_DEFAULT(Optional, object, PyObject_Type)
0086     using object::object;
0087 };
0088
0089 template <typename T>
0090 class Final : public object {
0091     PYBIND11_OBJECT_DEFAULT(Final, object, PyObject_Type)
0092     using object::object;
0093 };
0094
0095 template <typename T>
0096 class ClassVar : public object {
0097     PYBIND11_OBJECT_DEFAULT(ClassVar, object, PyObject_Type)
0098     using object::object;
0099 };
0100
0101 template <typename T>
0102 class TypeGuard : public bool_ {
0103     using bool_::bool_;
0104 };
0105
0106 template <typename T>
0107 class TypeIs : public bool_ {
0108     using bool_::bool_;
0109 };
0110
0111 class NoReturn : public none {
0112     using none::none;
0113 };
0114
0115 class Never : public none {
0116     using none::none;
0117 };
0118
0119 #if defined(PYBIND11_TYPING_H_HAS_STRING_LITERAL)
0120 template <size_t N>
0121 struct StringLiteral {
0122     constexpr StringLiteral(const char (&str)[N]) { std::copy_n(str, N, name); }
0123     char name[N];
0124 };
0125
0126 template <StringLiteral... StrLits>
0127 class Literal : public object {
0128     PYBIND11_OBJECT_DEFAULT(Literal, object, PyObject_Type)
0129 };
0130
0131 // Example syntax for creating a TypeVar.
0132 // typedef typing::TypeVar<"T"> TypeVarT;
0133 template <StringLiteral>
0134 class TypeVar : public object {
0135     PYBIND11_OBJECT_DEFAULT(TypeVar, object, PyObject_Type)
0136     using object::object;
0137 };
0138 #endif
0139
0140 PYBIND11_NAMESPACE_END(typing)
0141
0142 PYBIND11_NAMESPACE_BEGIN(detail)
0143
0144 template <typename... Types>
0145 struct handle_type_name<typing::Tuple<Types...>> {
0146     static constexpr auto name = const_name("tuple[")
0147                                  + ::pybind11::detail::concat(make_caster<Types>::name...)
0148                                  + const_name("]");
0149 };
0150
0151 template <>
0152 struct handle_type_name<typing::Tuple<>> {
0153     // PEP 484 specifies this syntax for an empty tuple
0154     static constexpr auto name = const_name("tuple[()]");
0155 };
0156
0157 template <typename T>
0158 struct handle_type_name<typing::Tuple<T, ellipsis>> {
0159     // PEP 484 specifies this syntax for a variable-length tuple
0160     static constexpr auto name
0161         = const_name("tuple[") + make_caster<T>::name + const_name(", ...]");
0162 };
0163
0164 template <typename K, typename V>
0165 struct handle_type_name<typing::Dict<K, V>> {
0166     static constexpr auto name = const_name("dict[") + make_caster<K>::name + const_name(", ")
0167                                  + make_caster<V>::name + const_name("]");
0168 };
0169
0170 template <typename T>
0171 struct handle_type_name<typing::List<T>> {
0172     static constexpr auto name = const_name("list[") + make_caster<T>::name + const_name("]");
0173 };
0174
0175 template <typename T>
0176 struct handle_type_name<typing::Set<T>> {
0177     static constexpr auto name = const_name("set[") + make_caster<T>::name + const_name("]");
0178 };
0179
0180 template <typename T>
0181 struct handle_type_name<typing::Iterable<T>> {
0182     static constexpr auto name
0183         = const_name("collections.abc.Iterable[") + make_caster<T>::name + const_name("]");
0184 };
0185
0186 template <typename T>
0187 struct handle_type_name<typing::Iterator<T>> {
0188     static constexpr auto name
0189         = const_name("collections.abc.Iterator[") + make_caster<T>::name + const_name("]");
0190 };
0191
0192 template <typename Return, typename... Args>
0193 struct handle_type_name<typing::Callable<Return(Args...)>> {
0194     using retval_type = conditional_t<std::is_same<Return, void>::value, void_type, Return>;
0195     static constexpr auto name
0196         = const_name("collections.abc.Callable[[")
0197           + ::pybind11::detail::concat(::pybind11::detail::arg_descr(make_caster<Args>::name)...)
0198           + const_name("], ") + ::pybind11::detail::return_descr(make_caster<retval_type>::name)
0199           + const_name("]");
0200 };
0201
0202 template <typename Return>
0203 struct handle_type_name<typing::Callable<Return(ellipsis)>> {
0204     // PEP 484 specifies this syntax for defining only return types of callables
0205     using retval_type = conditional_t<std::is_same<Return, void>::value, void_type, Return>;
0206     static constexpr auto name = const_name("collections.abc.Callable[..., ")
0207                                  + ::pybind11::detail::return_descr(make_caster<retval_type>::name)
0208                                  + const_name("]");
0209 };
0210
0211 template <typename T>
0212 struct handle_type_name<typing::Type<T>> {
0213     static constexpr auto name = const_name("type[") + make_caster<T>::name + const_name("]");
0214 };
0215
0216 template <typename... Types>
0217 struct handle_type_name<typing::Union<Types...>> {
0218     static constexpr auto name = ::pybind11::detail::union_concat(make_caster<Types>::name...);
0219 };
0220
0221 template <typename T>
0222 struct handle_type_name<typing::Optional<T>> {
0223     static constexpr auto name = make_caster<T>::name | make_caster<none>::name;
0224 };
0225
0226 template <typename T>
0227 struct handle_type_name<typing::Final<T>> {
0228     static constexpr auto name = const_name("typing.Final[")
0229                                  + ::pybind11::detail::return_descr(make_caster<T>::name)
0230                                  + const_name("]");
0231 };
0232
0233 template <typename T>
0234 struct handle_type_name<typing::ClassVar<T>> {
0235     static constexpr auto name
0236         = const_name("typing.ClassVar[") + make_caster<T>::name + const_name("]");
0237 };
0238
0239 template <typename T>
0240 struct handle_type_name<typing::TypeGuard<T>> {
0241     static constexpr auto name = const_name(PYBIND11_TYPE_GUARD_TYPE_HINT) + const_name("[")
0242                                  + make_caster<T>::name + const_name("]");
0243 };
0244
0245 template <typename T>
0246 struct handle_type_name<typing::TypeIs<T>> {
0247     static constexpr auto name = const_name(PYBIND11_TYPE_IS_TYPE_HINT) + const_name("[")
0248                                  + make_caster<T>::name + const_name("]");
0249 };
0250
0251 template <>
0252 struct handle_type_name<typing::NoReturn> {
0253     static constexpr auto name = const_name("typing.NoReturn");
0254 };
0255
0256 template <>
0257 struct handle_type_name<typing::Never> {
0258     static constexpr auto name = const_name(PYBIND11_NEVER_TYPE_HINT);
0259 };
0260
0261 #if defined(PYBIND11_TYPING_H_HAS_STRING_LITERAL)
0262 template <typing::StringLiteral StrLit>
0263 consteval auto sanitize_string_literal() {
0264     constexpr std::string_view v(StrLit.name);
0265     constexpr std::string_view special_chars("!@%{}-");
0266     constexpr auto num_special_chars = std::accumulate(
0267         special_chars.begin(), special_chars.end(), (size_t) 0, [&v](auto acc, const char &c) {
0268             return std::move(acc) + std::ranges::count(v, c);
0269         });
0270     char result[v.size() + num_special_chars + 1];
0271     size_t i = 0;
0272     for (auto c : StrLit.name) {
0273         if (special_chars.find(c) != std::string_view::npos) {
0274             result[i++] = '!';
0275         }
0276         result[i++] = c;
0277     }
0278     return typing::StringLiteral(result);
0279 }
0280
0281 template <typing::StringLiteral... Literals>
0282 struct handle_type_name<typing::Literal<Literals...>> {
0283     static constexpr auto name
0284         = const_name("typing.Literal[")
0285           + pybind11::detail::concat(const_name(sanitize_string_literal<Literals>().name)...)
0286           + const_name("]");
0287 };
0288 template <typing::StringLiteral StrLit>
0289 struct handle_type_name<typing::TypeVar<StrLit>> {
0290     static constexpr auto name = const_name(sanitize_string_literal<StrLit>().name);
0291 };
0292 #endif
0293
0294 PYBIND11_NAMESPACE_END(detail)
0295 PYBIND11_NAMESPACE_END(PYBIND11_NAMESPACE)