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_parameter_class)                                               \
0104     && (/* See #5201 */ !defined(__GNUC__)                                                        \
0105         || (__GNUC__ > 10 || (__GNUC__ == 10 && __GNUC_MINOR__ >= 3)))
0106 #    define PYBIND11_TYPING_H_HAS_STRING_LITERAL
0107 template <size_t N>
0108 struct StringLiteral {
0109     constexpr StringLiteral(const char (&str)[N]) { std::copy_n(str, N, name); }
0110     char name[N];
0111 };
0112
0113 template <StringLiteral... StrLits>
0114 class Literal : public object {
0115     PYBIND11_OBJECT_DEFAULT(Literal, object, PyObject_Type)
0116 };
0117
0118 // Example syntax for creating a TypeVar.
0119 // typedef typing::TypeVar<"T"> TypeVarT;
0120 template <StringLiteral>
0121 class TypeVar : public object {
0122     PYBIND11_OBJECT_DEFAULT(TypeVar, object, PyObject_Type)
0123     using object::object;
0124 };
0125 #endif
0126
0127 PYBIND11_NAMESPACE_END(typing)
0128
0129 PYBIND11_NAMESPACE_BEGIN(detail)
0130
0131 template <typename... Types>
0132 struct handle_type_name<typing::Tuple<Types...>> {
0133     static constexpr auto name = const_name("tuple[")
0134                                  + ::pybind11::detail::concat(make_caster<Types>::name...)
0135                                  + const_name("]");
0136 };
0137
0138 template <>
0139 struct handle_type_name<typing::Tuple<>> {
0140     // PEP 484 specifies this syntax for an empty tuple
0141     static constexpr auto name = const_name("tuple[()]");
0142 };
0143
0144 template <typename T>
0145 struct handle_type_name<typing::Tuple<T, ellipsis>> {
0146     // PEP 484 specifies this syntax for a variable-length tuple
0147     static constexpr auto name
0148         = const_name("tuple[") + make_caster<T>::name + const_name(", ...]");
0149 };
0150
0151 template <typename K, typename V>
0152 struct handle_type_name<typing::Dict<K, V>> {
0153     static constexpr auto name = const_name("dict[") + make_caster<K>::name + const_name(", ")
0154                                  + make_caster<V>::name + const_name("]");
0155 };
0156
0157 template <typename T>
0158 struct handle_type_name<typing::List<T>> {
0159     static constexpr auto name = const_name("list[") + make_caster<T>::name + const_name("]");
0160 };
0161
0162 template <typename T>
0163 struct handle_type_name<typing::Set<T>> {
0164     static constexpr auto name = const_name("set[") + make_caster<T>::name + const_name("]");
0165 };
0166
0167 template <typename T>
0168 struct handle_type_name<typing::Iterable<T>> {
0169     static constexpr auto name = const_name("Iterable[") + make_caster<T>::name + const_name("]");
0170 };
0171
0172 template <typename T>
0173 struct handle_type_name<typing::Iterator<T>> {
0174     static constexpr auto name = const_name("Iterator[") + make_caster<T>::name + const_name("]");
0175 };
0176
0177 template <typename Return, typename... Args>
0178 struct handle_type_name<typing::Callable<Return(Args...)>> {
0179     using retval_type = conditional_t<std::is_same<Return, void>::value, void_type, Return>;
0180     static constexpr auto name
0181         = const_name("Callable[[") + ::pybind11::detail::concat(make_caster<Args>::name...)
0182           + const_name("], ") + make_caster<retval_type>::name + const_name("]");
0183 };
0184
0185 template <typename Return>
0186 struct handle_type_name<typing::Callable<Return(ellipsis)>> {
0187     // PEP 484 specifies this syntax for defining only return types of callables
0188     using retval_type = conditional_t<std::is_same<Return, void>::value, void_type, Return>;
0189     static constexpr auto name
0190         = const_name("Callable[..., ") + make_caster<retval_type>::name + const_name("]");
0191 };
0192
0193 template <typename T>
0194 struct handle_type_name<typing::Type<T>> {
0195     static constexpr auto name = const_name("type[") + make_caster<T>::name + const_name("]");
0196 };
0197
0198 template <typename... Types>
0199 struct handle_type_name<typing::Union<Types...>> {
0200     static constexpr auto name = const_name("Union[")
0201                                  + ::pybind11::detail::concat(make_caster<Types>::name...)
0202                                  + const_name("]");
0203 };
0204
0205 template <typename T>
0206 struct handle_type_name<typing::Optional<T>> {
0207     static constexpr auto name = const_name("Optional[") + make_caster<T>::name + const_name("]");
0208 };
0209
0210 template <typename T>
0211 struct handle_type_name<typing::TypeGuard<T>> {
0212     static constexpr auto name = const_name("TypeGuard[") + make_caster<T>::name + const_name("]");
0213 };
0214
0215 template <typename T>
0216 struct handle_type_name<typing::TypeIs<T>> {
0217     static constexpr auto name = const_name("TypeIs[") + make_caster<T>::name + const_name("]");
0218 };
0219
0220 template <>
0221 struct handle_type_name<typing::NoReturn> {
0222     static constexpr auto name = const_name("NoReturn");
0223 };
0224
0225 template <>
0226 struct handle_type_name<typing::Never> {
0227     static constexpr auto name = const_name("Never");
0228 };
0229
0230 #if defined(PYBIND11_TYPING_H_HAS_STRING_LITERAL)
0231 template <typing::StringLiteral... Literals>
0232 struct handle_type_name<typing::Literal<Literals...>> {
0233     static constexpr auto name = const_name("Literal[")
0234                                  + pybind11::detail::concat(const_name(Literals.name)...)
0235                                  + const_name("]");
0236 };
0237 template <typing::StringLiteral StrLit>
0238 struct handle_type_name<typing::TypeVar<StrLit>> {
0239     static constexpr auto name = const_name(StrLit.name);
0240 };
0241 #endif
0242
0243 PYBIND11_NAMESPACE_END(detail)
0244 PYBIND11_NAMESPACE_END(PYBIND11_NAMESPACE)