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 PYBIND11_NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
0020 PYBIND11_NAMESPACE_BEGIN(typing)
0021
0022 /*
0023     The following types can be used to direct pybind11-generated docstrings
0024     to have have more explicit types (e.g., `list[str]` instead of `list`).
0025     Just use these in place of existing types.
0026
0027     There is no additional enforcement of types at runtime.
0028 */
0029
0030 template <typename... Types>
0031 class Tuple : public tuple {
0032     using tuple::tuple;
0033 };
0034
0035 template <typename K, typename V>
0036 class Dict : public dict {
0037     using dict::dict;
0038 };
0039
0040 template <typename T>
0041 class List : public list {
0042     using list::list;
0043 };
0044
0045 template <typename T>
0046 class Set : public set {
0047     using set::set;
0048 };
0049
0050 template <typename T>
0051 class Iterable : public iterable {
0052     using iterable::iterable;
0053 };
0054
0055 template <typename T>
0056 class Iterator : public iterator {
0057     using iterator::iterator;
0058 };
0059
0060 template <typename Signature>
0061 class Callable;
0062
0063 template <typename Return, typename... Args>
0064 class Callable<Return(Args...)> : public function {
0065     using function::function;
0066 };
0067
0068 template <typename T>
0069 class Type : public type {
0070     using type::type;
0071 };
0072
0073 template <typename... Types>
0074 class Union : public object {
0075     PYBIND11_OBJECT_DEFAULT(Union, object, PyObject_Type)
0076     using object::object;
0077 };
0078
0079 template <typename T>
0080 class Optional : public object {
0081     PYBIND11_OBJECT_DEFAULT(Optional, object, PyObject_Type)
0082     using object::object;
0083 };
0084
0085 template <typename T>
0086 class TypeGuard : public bool_ {
0087     using bool_::bool_;
0088 };
0089
0090 template <typename T>
0091 class TypeIs : public bool_ {
0092     using bool_::bool_;
0093 };
0094
0095 class NoReturn : public none {
0096     using none::none;
0097 };
0098
0099 class Never : public none {
0100     using none::none;
0101 };
0102
0103 #if defined(__cpp_nontype_template_args) && __cpp_nontype_template_args >= 201911L
0104 #    define PYBIND11_TYPING_H_HAS_STRING_LITERAL
0105 template <size_t N>
0106 struct StringLiteral {
0107     constexpr StringLiteral(const char (&str)[N]) { std::copy_n(str, N, name); }
0108     char name[N];
0109 };
0110
0111 template <StringLiteral... StrLits>
0112 class Literal : public object {
0113     PYBIND11_OBJECT_DEFAULT(Literal, object, PyObject_Type)
0114 };
0115
0116 // Example syntax for creating a TypeVar.
0117 // typedef typing::TypeVar<"T"> TypeVarT;
0118 template <StringLiteral>
0119 class TypeVar : public object {
0120     PYBIND11_OBJECT_DEFAULT(TypeVar, object, PyObject_Type)
0121     using object::object;
0122 };
0123 #endif
0124
0125 PYBIND11_NAMESPACE_END(typing)
0126
0127 PYBIND11_NAMESPACE_BEGIN(detail)
0128
0129 template <typename... Types>
0130 struct handle_type_name<typing::Tuple<Types...>> {
0131     static constexpr auto name = const_name("tuple[")
0132                                  + ::pybind11::detail::concat(make_caster<Types>::name...)
0133                                  + const_name("]");
0134 };
0135
0136 template <>
0137 struct handle_type_name<typing::Tuple<>> {
0138     // PEP 484 specifies this syntax for an empty tuple
0139     static constexpr auto name = const_name("tuple[()]");
0140 };
0141
0142 template <typename T>
0143 struct handle_type_name<typing::Tuple<T, ellipsis>> {
0144     // PEP 484 specifies this syntax for a variable-length tuple
0145     static constexpr auto name
0146         = const_name("tuple[") + make_caster<T>::name + const_name(", ...]");
0147 };
0148
0149 template <typename K, typename V>
0150 struct handle_type_name<typing::Dict<K, V>> {
0151     static constexpr auto name = const_name("dict[") + make_caster<K>::name + const_name(", ")
0152                                  + make_caster<V>::name + const_name("]");
0153 };
0154
0155 template <typename T>
0156 struct handle_type_name<typing::List<T>> {
0157     static constexpr auto name = const_name("list[") + make_caster<T>::name + const_name("]");
0158 };
0159
0160 template <typename T>
0161 struct handle_type_name<typing::Set<T>> {
0162     static constexpr auto name = const_name("set[") + make_caster<T>::name + const_name("]");
0163 };
0164
0165 template <typename T>
0166 struct handle_type_name<typing::Iterable<T>> {
0167     static constexpr auto name = const_name("Iterable[") + make_caster<T>::name + const_name("]");
0168 };
0169
0170 template <typename T>
0171 struct handle_type_name<typing::Iterator<T>> {
0172     static constexpr auto name = const_name("Iterator[") + make_caster<T>::name + const_name("]");
0173 };
0174
0175 template <typename Return, typename... Args>
0176 struct handle_type_name<typing::Callable<Return(Args...)>> {
0177     using retval_type = conditional_t<std::is_same<Return, void>::value, void_type, Return>;
0178     static constexpr auto name
0179         = const_name("Callable[[") + ::pybind11::detail::concat(make_caster<Args>::name...)
0180           + const_name("], ") + make_caster<retval_type>::name + const_name("]");
0181 };
0182
0183 template <typename Return>
0184 struct handle_type_name<typing::Callable<Return(ellipsis)>> {
0185     // PEP 484 specifies this syntax for defining only return types of callables
0186     using retval_type = conditional_t<std::is_same<Return, void>::value, void_type, Return>;
0187     static constexpr auto name
0188         = const_name("Callable[..., ") + make_caster<retval_type>::name + const_name("]");
0189 };
0190
0191 template <typename T>
0192 struct handle_type_name<typing::Type<T>> {
0193     static constexpr auto name = const_name("type[") + make_caster<T>::name + const_name("]");
0194 };
0195
0196 template <typename... Types>
0197 struct handle_type_name<typing::Union<Types...>> {
0198     static constexpr auto name = const_name("Union[")
0199                                  + ::pybind11::detail::concat(make_caster<Types>::name...)
0200                                  + const_name("]");
0201 };
0202
0203 template <typename T>
0204 struct handle_type_name<typing::Optional<T>> {
0205     static constexpr auto name = const_name("Optional[") + make_caster<T>::name + const_name("]");
0206 };
0207
0208 template <typename T>
0209 struct handle_type_name<typing::TypeGuard<T>> {
0210     static constexpr auto name = const_name("TypeGuard[") + make_caster<T>::name + const_name("]");
0211 };
0212
0213 template <typename T>
0214 struct handle_type_name<typing::TypeIs<T>> {
0215     static constexpr auto name = const_name("TypeIs[") + make_caster<T>::name + const_name("]");
0216 };
0217
0218 template <>
0219 struct handle_type_name<typing::NoReturn> {
0220     static constexpr auto name = const_name("NoReturn");
0221 };
0222
0223 template <>
0224 struct handle_type_name<typing::Never> {
0225     static constexpr auto name = const_name("Never");
0226 };
0227
0228 #if defined(PYBIND11_TYPING_H_HAS_STRING_LITERAL)
0229 template <typing::StringLiteral... Literals>
0230 struct handle_type_name<typing::Literal<Literals...>> {
0231     static constexpr auto name = const_name("Literal[")
0232                                  + pybind11::detail::concat(const_name(Literals.name)...)
0233                                  + const_name("]");
0234 };
0235 template <typing::StringLiteral StrLit>
0236 struct handle_type_name<typing::TypeVar<StrLit>> {
0237     static constexpr auto name = const_name(StrLit.name);
0238 };
0239 #endif
0240
0241 PYBIND11_NAMESPACE_END(detail)
0242 PYBIND11_NAMESPACE_END(PYBIND11_NAMESPACE)