Adding pybind11 v2.2.4 to repo
[tidl/tidl-api.git] / tidl_api / pybind11 / include / pybind11 / pytypes.h
1 /*
2     pybind11/pytypes.h: Convenience wrapper classes for basic Python types
4     Copyright (c) 2016 Wenzel Jakob <wenzel.jakob@epfl.ch>
6     All rights reserved. Use of this source code is governed by a
7     BSD-style license that can be found in the LICENSE file.
8 */
10 #pragma once
12 #include "detail/common.h"
13 #include "buffer_info.h"
14 #include <utility>
15 #include <type_traits>
17 NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
19 /* A few forward declarations */
20 class handle; class object;
21 class str; class iterator;
22 struct arg; struct arg_v;
24 NAMESPACE_BEGIN(detail)
25 class args_proxy;
26 inline bool isinstance_generic(handle obj, const std::type_info &tp);
28 // Accessor forward declarations
29 template <typename Policy> class accessor;
30 namespace accessor_policies {
31     struct obj_attr;
32     struct str_attr;
33     struct generic_item;
34     struct sequence_item;
35     struct list_item;
36     struct tuple_item;
37 }
38 using obj_attr_accessor = accessor<accessor_policies::obj_attr>;
39 using str_attr_accessor = accessor<accessor_policies::str_attr>;
40 using item_accessor = accessor<accessor_policies::generic_item>;
41 using sequence_accessor = accessor<accessor_policies::sequence_item>;
42 using list_accessor = accessor<accessor_policies::list_item>;
43 using tuple_accessor = accessor<accessor_policies::tuple_item>;
45 /// Tag and check to identify a class which implements the Python object API
46 class pyobject_tag { };
47 template <typename T> using is_pyobject = std::is_base_of<pyobject_tag, remove_reference_t<T>>;
49 /** \rst
50     A mixin class which adds common functions to `handle`, `object` and various accessors.
51     The only requirement for `Derived` is to implement ``PyObject *Derived::ptr() const``.
52 \endrst */
53 template <typename Derived>
54 class object_api : public pyobject_tag {
55     const Derived &derived() const { return static_cast<const Derived &>(*this); }
57 public:
58     /** \rst
59         Return an iterator equivalent to calling ``iter()`` in Python. The object
60         must be a collection which supports the iteration protocol.
61     \endrst */
62     iterator begin() const;
63     /// Return a sentinel which ends iteration.
64     iterator end() const;
66     /** \rst
67         Return an internal functor to invoke the object's sequence protocol. Casting
68         the returned ``detail::item_accessor`` instance to a `handle` or `object`
69         subclass causes a corresponding call to ``__getitem__``. Assigning a `handle`
70         or `object` subclass causes a call to ``__setitem__``.
71     \endrst */
72     item_accessor operator[](handle key) const;
73     /// See above (the only difference is that they key is provided as a string literal)
74     item_accessor operator[](const char *key) const;
76     /** \rst
77         Return an internal functor to access the object's attributes. Casting the
78         returned ``detail::obj_attr_accessor`` instance to a `handle` or `object`
79         subclass causes a corresponding call to ``getattr``. Assigning a `handle`
80         or `object` subclass causes a call to ``setattr``.
81     \endrst */
82     obj_attr_accessor attr(handle key) const;
83     /// See above (the only difference is that they key is provided as a string literal)
84     str_attr_accessor attr(const char *key) const;
86     /** \rst
87         Matches * unpacking in Python, e.g. to unpack arguments out of a ``tuple``
88         or ``list`` for a function call. Applying another * to the result yields
89         ** unpacking, e.g. to unpack a dict as function keyword arguments.
90         See :ref:`calling_python_functions`.
91     \endrst */
92     args_proxy operator*() const;
94     /// Check if the given item is contained within this object, i.e. ``item in obj``.
95     template <typename T> bool contains(T &&item) const;
97     /** \rst
98         Assuming the Python object is a function or implements the ``__call__``
99         protocol, ``operator()`` invokes the underlying function, passing an
100         arbitrary set of parameters. The result is returned as a `object` and
101         may need to be converted back into a Python object using `handle::cast()`.
103         When some of the arguments cannot be converted to Python objects, the
104         function will throw a `cast_error` exception. When the Python function
105         call fails, a `error_already_set` exception is thrown.
106     \endrst */
107     template <return_value_policy policy = return_value_policy::automatic_reference, typename... Args>
108     object operator()(Args &&...args) const;
109     template <return_value_policy policy = return_value_policy::automatic_reference, typename... Args>
110     PYBIND11_DEPRECATED("call(...) was deprecated in favor of operator()(...)")
111         object call(Args&&... args) const;
113     /// Equivalent to ``obj is other`` in Python.
114     bool is(object_api const& other) const { return derived().ptr() == other.derived().ptr(); }
115     /// Equivalent to ``obj is None`` in Python.
116     bool is_none() const { return derived().ptr() == Py_None; }
117     PYBIND11_DEPRECATED("Use py::str(obj) instead")
118     pybind11::str str() const;
120     /// Get or set the object's docstring, i.e. ``obj.__doc__``.
121     str_attr_accessor doc() const;
123     /// Return the object's current reference count
124     int ref_count() const { return static_cast<int>(Py_REFCNT(derived().ptr())); }
125     /// Return a handle to the Python type object underlying the instance
126     handle get_type() const;
127 };
129 NAMESPACE_END(detail)
131 /** \rst
132     Holds a reference to a Python object (no reference counting)
134     The `handle` class is a thin wrapper around an arbitrary Python object (i.e. a
135     ``PyObject *`` in Python's C API). It does not perform any automatic reference
136     counting and merely provides a basic C++ interface to various Python API functions.
138     .. seealso::
139         The `object` class inherits from `handle` and adds automatic reference
140         counting features.
141 \endrst */
142 class handle : public detail::object_api<handle> {
143 public:
144     /// The default constructor creates a handle with a ``nullptr``-valued pointer
145     handle() = default;
146     /// Creates a ``handle`` from the given raw Python object pointer
147     handle(PyObject *ptr) : m_ptr(ptr) { } // Allow implicit conversion from PyObject*
149     /// Return the underlying ``PyObject *`` pointer
150     PyObject *ptr() const { return m_ptr; }
151     PyObject *&ptr() { return m_ptr; }
153     /** \rst
154         Manually increase the reference count of the Python object. Usually, it is
155         preferable to use the `object` class which derives from `handle` and calls
156         this function automatically. Returns a reference to itself.
157     \endrst */
158     const handle& inc_ref() const & { Py_XINCREF(m_ptr); return *this; }
160     /** \rst
161         Manually decrease the reference count of the Python object. Usually, it is
162         preferable to use the `object` class which derives from `handle` and calls
163         this function automatically. Returns a reference to itself.
164     \endrst */
165     const handle& dec_ref() const & { Py_XDECREF(m_ptr); return *this; }
167     /** \rst
168         Attempt to cast the Python object into the given C++ type. A `cast_error`
169         will be throw upon failure.
170     \endrst */
171     template <typename T> T cast() const;
172     /// Return ``true`` when the `handle` wraps a valid Python object
173     explicit operator bool() const { return m_ptr != nullptr; }
174     /** \rst
175         Deprecated: Check that the underlying pointers are the same.
176         Equivalent to ``obj1 is obj2`` in Python.
177     \endrst */
178     PYBIND11_DEPRECATED("Use obj1.is(obj2) instead")
179     bool operator==(const handle &h) const { return m_ptr == h.m_ptr; }
180     PYBIND11_DEPRECATED("Use !obj1.is(obj2) instead")
181     bool operator!=(const handle &h) const { return m_ptr != h.m_ptr; }
182     PYBIND11_DEPRECATED("Use handle::operator bool() instead")
183     bool check() const { return m_ptr != nullptr; }
184 protected:
185     PyObject *m_ptr = nullptr;
186 };
188 /** \rst
189     Holds a reference to a Python object (with reference counting)
191     Like `handle`, the `object` class is a thin wrapper around an arbitrary Python
192     object (i.e. a ``PyObject *`` in Python's C API). In contrast to `handle`, it
193     optionally increases the object's reference count upon construction, and it
194     *always* decreases the reference count when the `object` instance goes out of
195     scope and is destructed. When using `object` instances consistently, it is much
196     easier to get reference counting right at the first attempt.
197 \endrst */
198 class object : public handle {
199 public:
200     object() = default;
201     PYBIND11_DEPRECATED("Use reinterpret_borrow<object>() or reinterpret_steal<object>()")
202     object(handle h, bool is_borrowed) : handle(h) { if (is_borrowed) inc_ref(); }
203     /// Copy constructor; always increases the reference count
204     object(const object &o) : handle(o) { inc_ref(); }
205     /// Move constructor; steals the object from ``other`` and preserves its reference count
206     object(object &&other) noexcept { m_ptr = other.m_ptr; other.m_ptr = nullptr; }
207     /// Destructor; automatically calls `handle::dec_ref()`
208     ~object() { dec_ref(); }
210     /** \rst
211         Resets the internal pointer to ``nullptr`` without without decreasing the
212         object's reference count. The function returns a raw handle to the original
213         Python object.
214     \endrst */
215     handle release() {
216       PyObject *tmp = m_ptr;
217       m_ptr = nullptr;
218       return handle(tmp);
219     }
221     object& operator=(const object &other) {
222         other.inc_ref();
223         dec_ref();
224         m_ptr = other.m_ptr;
225         return *this;
226     }
228     object& operator=(object &&other) noexcept {
229         if (this != &other) {
230             handle temp(m_ptr);
231             m_ptr = other.m_ptr;
232             other.m_ptr = nullptr;
233             temp.dec_ref();
234         }
235         return *this;
236     }
238     // Calling cast() on an object lvalue just copies (via handle::cast)
239     template <typename T> T cast() const &;
240     // Calling on an object rvalue does a move, if needed and/or possible
241     template <typename T> T cast() &&;
243 protected:
244     // Tags for choosing constructors from raw PyObject *
245     struct borrowed_t { };
246     struct stolen_t { };
248     template <typename T> friend T reinterpret_borrow(handle);
249     template <typename T> friend T reinterpret_steal(handle);
251 public:
252     // Only accessible from derived classes and the reinterpret_* functions
253     object(handle h, borrowed_t) : handle(h) { inc_ref(); }
254     object(handle h, stolen_t) : handle(h) { }
255 };
257 /** \rst
258     Declare that a `handle` or ``PyObject *`` is a certain type and borrow the reference.
259     The target type ``T`` must be `object` or one of its derived classes. The function
260     doesn't do any conversions or checks. It's up to the user to make sure that the
261     target type is correct.
263     .. code-block:: cpp
265         PyObject *p = PyList_GetItem(obj, index);
266         py::object o = reinterpret_borrow<py::object>(p);
267         // or
268         py::tuple t = reinterpret_borrow<py::tuple>(p); // <-- `p` must be already be a `tuple`
269 \endrst */
270 template <typename T> T reinterpret_borrow(handle h) { return {h, object::borrowed_t{}}; }
272 /** \rst
273     Like `reinterpret_borrow`, but steals the reference.
275      .. code-block:: cpp
277         PyObject *p = PyObject_Str(obj);
278         py::str s = reinterpret_steal<py::str>(p); // <-- `p` must be already be a `str`
279 \endrst */
280 template <typename T> T reinterpret_steal(handle h) { return {h, object::stolen_t{}}; }
282 NAMESPACE_BEGIN(detail)
283 inline std::string error_string();
284 NAMESPACE_END(detail)
286 /// Fetch and hold an error which was already set in Python.  An instance of this is typically
287 /// thrown to propagate python-side errors back through C++ which can either be caught manually or
288 /// else falls back to the function dispatcher (which then raises the captured error back to
289 /// python).
290 class error_already_set : public std::runtime_error {
291 public:
292     /// Constructs a new exception from the current Python error indicator, if any.  The current
293     /// Python error indicator will be cleared.
294     error_already_set() : std::runtime_error(detail::error_string()) {
295         PyErr_Fetch(&type.ptr(), &value.ptr(), &trace.ptr());
296     }
298     inline ~error_already_set();
300     /// Give the currently-held error back to Python, if any.  If there is currently a Python error
301     /// already set it is cleared first.  After this call, the current object no longer stores the
302     /// error variables (but the `.what()` string is still available).
303     void restore() { PyErr_Restore(type.release().ptr(), value.release().ptr(), trace.release().ptr()); }
305     // Does nothing; provided for backwards compatibility.
306     PYBIND11_DEPRECATED("Use of error_already_set.clear() is deprecated")
307     void clear() {}
309     /// Check if the currently trapped error type matches the given Python exception class (or a
310     /// subclass thereof).  May also be passed a tuple to search for any exception class matches in
311     /// the given tuple.
312     bool matches(handle ex) const { return PyErr_GivenExceptionMatches(ex.ptr(), type.ptr()); }
314 private:
315     object type, value, trace;
316 };
318 /** \defgroup python_builtins _
319     Unless stated otherwise, the following C++ functions behave the same
320     as their Python counterparts.
321  */
323 /** \ingroup python_builtins
324     \rst
325     Return true if ``obj`` is an instance of ``T``. Type ``T`` must be a subclass of
326     `object` or a class which was exposed to Python as ``py::class_<T>``.
327 \endrst */
328 template <typename T, detail::enable_if_t<std::is_base_of<object, T>::value, int> = 0>
329 bool isinstance(handle obj) { return T::check_(obj); }
331 template <typename T, detail::enable_if_t<!std::is_base_of<object, T>::value, int> = 0>
332 bool isinstance(handle obj) { return detail::isinstance_generic(obj, typeid(T)); }
334 template <> inline bool isinstance<handle>(handle obj) = delete;
335 template <> inline bool isinstance<object>(handle obj) { return obj.ptr() != nullptr; }
337 /// \ingroup python_builtins
338 /// Return true if ``obj`` is an instance of the ``type``.
339 inline bool isinstance(handle obj, handle type) {
340     const auto result = PyObject_IsInstance(obj.ptr(), type.ptr());
341     if (result == -1)
342         throw error_already_set();
343     return result != 0;
346 /// \addtogroup python_builtins
347 /// @{
348 inline bool hasattr(handle obj, handle name) {
349     return PyObject_HasAttr(obj.ptr(), name.ptr()) == 1;
352 inline bool hasattr(handle obj, const char *name) {
353     return PyObject_HasAttrString(obj.ptr(), name) == 1;
356 inline object getattr(handle obj, handle name) {
357     PyObject *result = PyObject_GetAttr(obj.ptr(), name.ptr());
358     if (!result) { throw error_already_set(); }
359     return reinterpret_steal<object>(result);
362 inline object getattr(handle obj, const char *name) {
363     PyObject *result = PyObject_GetAttrString(obj.ptr(), name);
364     if (!result) { throw error_already_set(); }
365     return reinterpret_steal<object>(result);
368 inline object getattr(handle obj, handle name, handle default_) {
369     if (PyObject *result = PyObject_GetAttr(obj.ptr(), name.ptr())) {
370         return reinterpret_steal<object>(result);
371     } else {
372         PyErr_Clear();
373         return reinterpret_borrow<object>(default_);
374     }
377 inline object getattr(handle obj, const char *name, handle default_) {
378     if (PyObject *result = PyObject_GetAttrString(obj.ptr(), name)) {
379         return reinterpret_steal<object>(result);
380     } else {
381         PyErr_Clear();
382         return reinterpret_borrow<object>(default_);
383     }
386 inline void setattr(handle obj, handle name, handle value) {
387     if (PyObject_SetAttr(obj.ptr(), name.ptr(), value.ptr()) != 0) { throw error_already_set(); }
390 inline void setattr(handle obj, const char *name, handle value) {
391     if (PyObject_SetAttrString(obj.ptr(), name, value.ptr()) != 0) { throw error_already_set(); }
394 inline ssize_t hash(handle obj) {
395     auto h = PyObject_Hash(obj.ptr());
396     if (h == -1) { throw error_already_set(); }
397     return h;
400 /// @} python_builtins
402 NAMESPACE_BEGIN(detail)
403 inline handle get_function(handle value) {
404     if (value) {
405 #if PY_MAJOR_VERSION >= 3
406         if (PyInstanceMethod_Check(value.ptr()))
407             value = PyInstanceMethod_GET_FUNCTION(value.ptr());
408         else
409 #endif
410         if (PyMethod_Check(value.ptr()))
411             value = PyMethod_GET_FUNCTION(value.ptr());
412     }
413     return value;
416 // Helper aliases/functions to support implicit casting of values given to python accessors/methods.
417 // When given a pyobject, this simply returns the pyobject as-is; for other C++ type, the value goes
418 // through pybind11::cast(obj) to convert it to an `object`.
419 template <typename T, enable_if_t<is_pyobject<T>::value, int> = 0>
420 auto object_or_cast(T &&o) -> decltype(std::forward<T>(o)) { return std::forward<T>(o); }
421 // The following casting version is implemented in cast.h:
422 template <typename T, enable_if_t<!is_pyobject<T>::value, int> = 0>
423 object object_or_cast(T &&o);
424 // Match a PyObject*, which we want to convert directly to handle via its converting constructor
425 inline handle object_or_cast(PyObject *ptr) { return ptr; }
428 template <typename Policy>
429 class accessor : public object_api<accessor<Policy>> {
430     using key_type = typename Policy::key_type;
432 public:
433     accessor(handle obj, key_type key) : obj(obj), key(std::move(key)) { }
434     accessor(const accessor &) = default;
435     accessor(accessor &&) = default;
437     // accessor overload required to override default assignment operator (templates are not allowed
438     // to replace default compiler-generated assignments).
439     void operator=(const accessor &a) && { std::move(*this).operator=(handle(a)); }
440     void operator=(const accessor &a) & { operator=(handle(a)); }
442     template <typename T> void operator=(T &&value) && {
443         Policy::set(obj, key, object_or_cast(std::forward<T>(value)));
444     }
445     template <typename T> void operator=(T &&value) & {
446         get_cache() = reinterpret_borrow<object>(object_or_cast(std::forward<T>(value)));
447     }
449     template <typename T = Policy>
450     PYBIND11_DEPRECATED("Use of obj.attr(...) as bool is deprecated in favor of pybind11::hasattr(obj, ...)")
451     explicit operator enable_if_t<std::is_same<T, accessor_policies::str_attr>::value ||
452             std::is_same<T, accessor_policies::obj_attr>::value, bool>() const {
453         return hasattr(obj, key);
454     }
455     template <typename T = Policy>
456     PYBIND11_DEPRECATED("Use of obj[key] as bool is deprecated in favor of obj.contains(key)")
457     explicit operator enable_if_t<std::is_same<T, accessor_policies::generic_item>::value, bool>() const {
458         return obj.contains(key);
459     }
461     operator object() const { return get_cache(); }
462     PyObject *ptr() const { return get_cache().ptr(); }
463     template <typename T> T cast() const { return get_cache().template cast<T>(); }
465 private:
466     object &get_cache() const {
467         if (!cache) { cache = Policy::get(obj, key); }
468         return cache;
469     }
471 private:
472     handle obj;
473     key_type key;
474     mutable object cache;
475 };
477 NAMESPACE_BEGIN(accessor_policies)
478 struct obj_attr {
479     using key_type = object;
480     static object get(handle obj, handle key) { return getattr(obj, key); }
481     static void set(handle obj, handle key, handle val) { setattr(obj, key, val); }
482 };
484 struct str_attr {
485     using key_type = const char *;
486     static object get(handle obj, const char *key) { return getattr(obj, key); }
487     static void set(handle obj, const char *key, handle val) { setattr(obj, key, val); }
488 };
490 struct generic_item {
491     using key_type = object;
493     static object get(handle obj, handle key) {
494         PyObject *result = PyObject_GetItem(obj.ptr(), key.ptr());
495         if (!result) { throw error_already_set(); }
496         return reinterpret_steal<object>(result);
497     }
499     static void set(handle obj, handle key, handle val) {
500         if (PyObject_SetItem(obj.ptr(), key.ptr(), val.ptr()) != 0) { throw error_already_set(); }
501     }
502 };
504 struct sequence_item {
505     using key_type = size_t;
507     static object get(handle obj, size_t index) {
508         PyObject *result = PySequence_GetItem(obj.ptr(), static_cast<ssize_t>(index));
509         if (!result) { throw error_already_set(); }
510         return reinterpret_steal<object>(result);
511     }
513     static void set(handle obj, size_t index, handle val) {
514         // PySequence_SetItem does not steal a reference to 'val'
515         if (PySequence_SetItem(obj.ptr(), static_cast<ssize_t>(index), val.ptr()) != 0) {
516             throw error_already_set();
517         }
518     }
519 };
521 struct list_item {
522     using key_type = size_t;
524     static object get(handle obj, size_t index) {
525         PyObject *result = PyList_GetItem(obj.ptr(), static_cast<ssize_t>(index));
526         if (!result) { throw error_already_set(); }
527         return reinterpret_borrow<object>(result);
528     }
530     static void set(handle obj, size_t index, handle val) {
531         // PyList_SetItem steals a reference to 'val'
532         if (PyList_SetItem(obj.ptr(), static_cast<ssize_t>(index), val.inc_ref().ptr()) != 0) {
533             throw error_already_set();
534         }
535     }
536 };
538 struct tuple_item {
539     using key_type = size_t;
541     static object get(handle obj, size_t index) {
542         PyObject *result = PyTuple_GetItem(obj.ptr(), static_cast<ssize_t>(index));
543         if (!result) { throw error_already_set(); }
544         return reinterpret_borrow<object>(result);
545     }
547     static void set(handle obj, size_t index, handle val) {
548         // PyTuple_SetItem steals a reference to 'val'
549         if (PyTuple_SetItem(obj.ptr(), static_cast<ssize_t>(index), val.inc_ref().ptr()) != 0) {
550             throw error_already_set();
551         }
552     }
553 };
554 NAMESPACE_END(accessor_policies)
556 /// STL iterator template used for tuple, list, sequence and dict
557 template <typename Policy>
558 class generic_iterator : public Policy {
559     using It = generic_iterator;
561 public:
562     using difference_type = ssize_t;
563     using iterator_category = typename Policy::iterator_category;
564     using value_type = typename Policy::value_type;
565     using reference = typename Policy::reference;
566     using pointer = typename Policy::pointer;
568     generic_iterator() = default;
569     generic_iterator(handle seq, ssize_t index) : Policy(seq, index) { }
571     reference operator*() const { return Policy::dereference(); }
572     reference operator[](difference_type n) const { return *(*this + n); }
573     pointer operator->() const { return **this; }
575     It &operator++() { Policy::increment(); return *this; }
576     It operator++(int) { auto copy = *this; Policy::increment(); return copy; }
577     It &operator--() { Policy::decrement(); return *this; }
578     It operator--(int) { auto copy = *this; Policy::decrement(); return copy; }
579     It &operator+=(difference_type n) { Policy::advance(n); return *this; }
580     It &operator-=(difference_type n) { Policy::advance(-n); return *this; }
582     friend It operator+(const It &a, difference_type n) { auto copy = a; return copy += n; }
583     friend It operator+(difference_type n, const It &b) { return b + n; }
584     friend It operator-(const It &a, difference_type n) { auto copy = a; return copy -= n; }
585     friend difference_type operator-(const It &a, const It &b) { return a.distance_to(b); }
587     friend bool operator==(const It &a, const It &b) { return a.equal(b); }
588     friend bool operator!=(const It &a, const It &b) { return !(a == b); }
589     friend bool operator< (const It &a, const It &b) { return b - a > 0; }
590     friend bool operator> (const It &a, const It &b) { return b < a; }
591     friend bool operator>=(const It &a, const It &b) { return !(a < b); }
592     friend bool operator<=(const It &a, const It &b) { return !(a > b); }
593 };
595 NAMESPACE_BEGIN(iterator_policies)
596 /// Quick proxy class needed to implement ``operator->`` for iterators which can't return pointers
597 template <typename T>
598 struct arrow_proxy {
599     T value;
601     arrow_proxy(T &&value) : value(std::move(value)) { }
602     T *operator->() const { return &value; }
603 };
605 /// Lightweight iterator policy using just a simple pointer: see ``PySequence_Fast_ITEMS``
606 class sequence_fast_readonly {
607 protected:
608     using iterator_category = std::random_access_iterator_tag;
609     using value_type = handle;
610     using reference = const handle;
611     using pointer = arrow_proxy<const handle>;
613     sequence_fast_readonly(handle obj, ssize_t n) : ptr(PySequence_Fast_ITEMS(obj.ptr()) + n) { }
615     reference dereference() const { return *ptr; }
616     void increment() { ++ptr; }
617     void decrement() { --ptr; }
618     void advance(ssize_t n) { ptr += n; }
619     bool equal(const sequence_fast_readonly &b) const { return ptr == b.ptr; }
620     ssize_t distance_to(const sequence_fast_readonly &b) const { return ptr - b.ptr; }
622 private:
623     PyObject **ptr;
624 };
626 /// Full read and write access using the sequence protocol: see ``detail::sequence_accessor``
627 class sequence_slow_readwrite {
628 protected:
629     using iterator_category = std::random_access_iterator_tag;
630     using value_type = object;
631     using reference = sequence_accessor;
632     using pointer = arrow_proxy<const sequence_accessor>;
634     sequence_slow_readwrite(handle obj, ssize_t index) : obj(obj), index(index) { }
636     reference dereference() const { return {obj, static_cast<size_t>(index)}; }
637     void increment() { ++index; }
638     void decrement() { --index; }
639     void advance(ssize_t n) { index += n; }
640     bool equal(const sequence_slow_readwrite &b) const { return index == b.index; }
641     ssize_t distance_to(const sequence_slow_readwrite &b) const { return index - b.index; }
643 private:
644     handle obj;
645     ssize_t index;
646 };
648 /// Python's dictionary protocol permits this to be a forward iterator
649 class dict_readonly {
650 protected:
651     using iterator_category = std::forward_iterator_tag;
652     using value_type = std::pair<handle, handle>;
653     using reference = const value_type;
654     using pointer = arrow_proxy<const value_type>;
656     dict_readonly() = default;
657     dict_readonly(handle obj, ssize_t pos) : obj(obj), pos(pos) { increment(); }
659     reference dereference() const { return {key, value}; }
660     void increment() { if (!PyDict_Next(obj.ptr(), &pos, &key, &value)) { pos = -1; } }
661     bool equal(const dict_readonly &b) const { return pos == b.pos; }
663 private:
664     handle obj;
665     PyObject *key, *value;
666     ssize_t pos = -1;
667 };
668 NAMESPACE_END(iterator_policies)
670 #if !defined(PYPY_VERSION)
671 using tuple_iterator = generic_iterator<iterator_policies::sequence_fast_readonly>;
672 using list_iterator = generic_iterator<iterator_policies::sequence_fast_readonly>;
673 #else
674 using tuple_iterator = generic_iterator<iterator_policies::sequence_slow_readwrite>;
675 using list_iterator = generic_iterator<iterator_policies::sequence_slow_readwrite>;
676 #endif
678 using sequence_iterator = generic_iterator<iterator_policies::sequence_slow_readwrite>;
679 using dict_iterator = generic_iterator<iterator_policies::dict_readonly>;
681 inline bool PyIterable_Check(PyObject *obj) {
682     PyObject *iter = PyObject_GetIter(obj);
683     if (iter) {
684         Py_DECREF(iter);
685         return true;
686     } else {
687         PyErr_Clear();
688         return false;
689     }
692 inline bool PyNone_Check(PyObject *o) { return o == Py_None; }
694 inline bool PyUnicode_Check_Permissive(PyObject *o) { return PyUnicode_Check(o) || PYBIND11_BYTES_CHECK(o); }
696 class kwargs_proxy : public handle {
697 public:
698     explicit kwargs_proxy(handle h) : handle(h) { }
699 };
701 class args_proxy : public handle {
702 public:
703     explicit args_proxy(handle h) : handle(h) { }
704     kwargs_proxy operator*() const { return kwargs_proxy(*this); }
705 };
707 /// Python argument categories (using PEP 448 terms)
708 template <typename T> using is_keyword = std::is_base_of<arg, T>;
709 template <typename T> using is_s_unpacking = std::is_same<args_proxy, T>; // * unpacking
710 template <typename T> using is_ds_unpacking = std::is_same<kwargs_proxy, T>; // ** unpacking
711 template <typename T> using is_positional = satisfies_none_of<T,
712     is_keyword, is_s_unpacking, is_ds_unpacking
713 >;
714 template <typename T> using is_keyword_or_ds = satisfies_any_of<T, is_keyword, is_ds_unpacking>;
716 // Call argument collector forward declarations
717 template <return_value_policy policy = return_value_policy::automatic_reference>
718 class simple_collector;
719 template <return_value_policy policy = return_value_policy::automatic_reference>
720 class unpacking_collector;
722 NAMESPACE_END(detail)
724 // TODO: After the deprecated constructors are removed, this macro can be simplified by
725 //       inheriting ctors: `using Parent::Parent`. It's not an option right now because
726 //       the `using` statement triggers the parent deprecation warning even if the ctor
727 //       isn't even used.
728 #define PYBIND11_OBJECT_COMMON(Name, Parent, CheckFun) \
729     public: \
730         PYBIND11_DEPRECATED("Use reinterpret_borrow<"#Name">() or reinterpret_steal<"#Name">()") \
731         Name(handle h, bool is_borrowed) : Parent(is_borrowed ? Parent(h, borrowed_t{}) : Parent(h, stolen_t{})) { } \
732         Name(handle h, borrowed_t) : Parent(h, borrowed_t{}) { } \
733         Name(handle h, stolen_t) : Parent(h, stolen_t{}) { } \
734         PYBIND11_DEPRECATED("Use py::isinstance<py::python_type>(obj) instead") \
735         bool check() const { return m_ptr != nullptr && (bool) CheckFun(m_ptr); } \
736         static bool check_(handle h) { return h.ptr() != nullptr && CheckFun(h.ptr()); }
738 #define PYBIND11_OBJECT_CVT(Name, Parent, CheckFun, ConvertFun) \
739     PYBIND11_OBJECT_COMMON(Name, Parent, CheckFun) \
740     /* This is deliberately not 'explicit' to allow implicit conversion from object: */ \
741     Name(const object &o) \
742     : Parent(check_(o) ? o.inc_ref().ptr() : ConvertFun(o.ptr()), stolen_t{}) \
743     { if (!m_ptr) throw error_already_set(); } \
744     Name(object &&o) \
745     : Parent(check_(o) ? o.release().ptr() : ConvertFun(o.ptr()), stolen_t{}) \
746     { if (!m_ptr) throw error_already_set(); } \
747     template <typename Policy_> \
748     Name(const ::pybind11::detail::accessor<Policy_> &a) : Name(object(a)) { }
750 #define PYBIND11_OBJECT(Name, Parent, CheckFun) \
751     PYBIND11_OBJECT_COMMON(Name, Parent, CheckFun) \
752     /* This is deliberately not 'explicit' to allow implicit conversion from object: */ \
753     Name(const object &o) : Parent(o) { } \
754     Name(object &&o) : Parent(std::move(o)) { }
756 #define PYBIND11_OBJECT_DEFAULT(Name, Parent, CheckFun) \
757     PYBIND11_OBJECT(Name, Parent, CheckFun) \
758     Name() : Parent() { }
760 /// \addtogroup pytypes
761 /// @{
763 /** \rst
764     Wraps a Python iterator so that it can also be used as a C++ input iterator
766     Caveat: copying an iterator does not (and cannot) clone the internal
767     state of the Python iterable. This also applies to the post-increment
768     operator. This iterator should only be used to retrieve the current
769     value using ``operator*()``.
770 \endrst */
771 class iterator : public object {
772 public:
773     using iterator_category = std::input_iterator_tag;
774     using difference_type = ssize_t;
775     using value_type = handle;
776     using reference = const handle;
777     using pointer = const handle *;
779     PYBIND11_OBJECT_DEFAULT(iterator, object, PyIter_Check)
781     iterator& operator++() {
782         advance();
783         return *this;
784     }
786     iterator operator++(int) {
787         auto rv = *this;
788         advance();
789         return rv;
790     }
792     reference operator*() const {
793         if (m_ptr && !value.ptr()) {
794             auto& self = const_cast<iterator &>(*this);
795             self.advance();
796         }
797         return value;
798     }
800     pointer operator->() const { operator*(); return &value; }
802     /** \rst
803          The value which marks the end of the iteration. ``it == iterator::sentinel()``
804          is equivalent to catching ``StopIteration`` in Python.
806          .. code-block:: cpp
808              void foo(py::iterator it) {
809                  while (it != py::iterator::sentinel()) {
810                     // use `*it`
811                     ++it;
812                  }
813              }
814     \endrst */
815     static iterator sentinel() { return {}; }
817     friend bool operator==(const iterator &a, const iterator &b) { return a->ptr() == b->ptr(); }
818     friend bool operator!=(const iterator &a, const iterator &b) { return a->ptr() != b->ptr(); }
820 private:
821     void advance() {
822         value = reinterpret_steal<object>(PyIter_Next(m_ptr));
823         if (PyErr_Occurred()) { throw error_already_set(); }
824     }
826 private:
827     object value = {};
828 };
830 class iterable : public object {
831 public:
832     PYBIND11_OBJECT_DEFAULT(iterable, object, detail::PyIterable_Check)
833 };
835 class bytes;
837 class str : public object {
838 public:
839     PYBIND11_OBJECT_CVT(str, object, detail::PyUnicode_Check_Permissive, raw_str)
841     str(const char *c, size_t n)
842         : object(PyUnicode_FromStringAndSize(c, (ssize_t) n), stolen_t{}) {
843         if (!m_ptr) pybind11_fail("Could not allocate string object!");
844     }
846     // 'explicit' is explicitly omitted from the following constructors to allow implicit conversion to py::str from C++ string-like objects
847     str(const char *c = "")
848         : object(PyUnicode_FromString(c), stolen_t{}) {
849         if (!m_ptr) pybind11_fail("Could not allocate string object!");
850     }
852     str(const std::string &s) : str(s.data(), s.size()) { }
854     explicit str(const bytes &b);
856     /** \rst
857         Return a string representation of the object. This is analogous to
858         the ``str()`` function in Python.
859     \endrst */
860     explicit str(handle h) : object(raw_str(h.ptr()), stolen_t{}) { }
862     operator std::string() const {
863         object temp = *this;
864         if (PyUnicode_Check(m_ptr)) {
865             temp = reinterpret_steal<object>(PyUnicode_AsUTF8String(m_ptr));
866             if (!temp)
867                 pybind11_fail("Unable to extract string contents! (encoding issue)");
868         }
869         char *buffer;
870         ssize_t length;
871         if (PYBIND11_BYTES_AS_STRING_AND_SIZE(temp.ptr(), &buffer, &length))
872             pybind11_fail("Unable to extract string contents! (invalid type)");
873         return std::string(buffer, (size_t) length);
874     }
876     template <typename... Args>
877     str format(Args &&...args) const {
878         return attr("format")(std::forward<Args>(args)...);
879     }
881 private:
882     /// Return string representation -- always returns a new reference, even if already a str
883     static PyObject *raw_str(PyObject *op) {
884         PyObject *str_value = PyObject_Str(op);
885 #if PY_MAJOR_VERSION < 3
886         if (!str_value) throw error_already_set();
887         PyObject *unicode = PyUnicode_FromEncodedObject(str_value, "utf-8", nullptr);
888         Py_XDECREF(str_value); str_value = unicode;
889 #endif
890         return str_value;
891     }
892 };
893 /// @} pytypes
895 inline namespace literals {
896 /** \rst
897     String literal version of `str`
898  \endrst */
899 inline str operator"" _s(const char *s, size_t size) { return {s, size}; }
902 /// \addtogroup pytypes
903 /// @{
904 class bytes : public object {
905 public:
906     PYBIND11_OBJECT(bytes, object, PYBIND11_BYTES_CHECK)
908     // Allow implicit conversion:
909     bytes(const char *c = "")
910         : object(PYBIND11_BYTES_FROM_STRING(c), stolen_t{}) {
911         if (!m_ptr) pybind11_fail("Could not allocate bytes object!");
912     }
914     bytes(const char *c, size_t n)
915         : object(PYBIND11_BYTES_FROM_STRING_AND_SIZE(c, (ssize_t) n), stolen_t{}) {
916         if (!m_ptr) pybind11_fail("Could not allocate bytes object!");
917     }
919     // Allow implicit conversion:
920     bytes(const std::string &s) : bytes(s.data(), s.size()) { }
922     explicit bytes(const pybind11::str &s);
924     operator std::string() const {
925         char *buffer;
926         ssize_t length;
927         if (PYBIND11_BYTES_AS_STRING_AND_SIZE(m_ptr, &buffer, &length))
928             pybind11_fail("Unable to extract bytes contents!");
929         return std::string(buffer, (size_t) length);
930     }
931 };
933 inline bytes::bytes(const pybind11::str &s) {
934     object temp = s;
935     if (PyUnicode_Check(s.ptr())) {
936         temp = reinterpret_steal<object>(PyUnicode_AsUTF8String(s.ptr()));
937         if (!temp)
938             pybind11_fail("Unable to extract string contents! (encoding issue)");
939     }
940     char *buffer;
941     ssize_t length;
942     if (PYBIND11_BYTES_AS_STRING_AND_SIZE(temp.ptr(), &buffer, &length))
943         pybind11_fail("Unable to extract string contents! (invalid type)");
944     auto obj = reinterpret_steal<object>(PYBIND11_BYTES_FROM_STRING_AND_SIZE(buffer, length));
945     if (!obj)
946         pybind11_fail("Could not allocate bytes object!");
947     m_ptr = obj.release().ptr();
950 inline str::str(const bytes& b) {
951     char *buffer;
952     ssize_t length;
953     if (PYBIND11_BYTES_AS_STRING_AND_SIZE(b.ptr(), &buffer, &length))
954         pybind11_fail("Unable to extract bytes contents!");
955     auto obj = reinterpret_steal<object>(PyUnicode_FromStringAndSize(buffer, (ssize_t) length));
956     if (!obj)
957         pybind11_fail("Could not allocate string object!");
958     m_ptr = obj.release().ptr();
961 class none : public object {
962 public:
963     PYBIND11_OBJECT(none, object, detail::PyNone_Check)
964     none() : object(Py_None, borrowed_t{}) { }
965 };
967 class bool_ : public object {
968 public:
969     PYBIND11_OBJECT_CVT(bool_, object, PyBool_Check, raw_bool)
970     bool_() : object(Py_False, borrowed_t{}) { }
971     // Allow implicit conversion from and to `bool`:
972     bool_(bool value) : object(value ? Py_True : Py_False, borrowed_t{}) { }
973     operator bool() const { return m_ptr && PyLong_AsLong(m_ptr) != 0; }
975 private:
976     /// Return the truth value of an object -- always returns a new reference
977     static PyObject *raw_bool(PyObject *op) {
978         const auto value = PyObject_IsTrue(op);
979         if (value == -1) return nullptr;
980         return handle(value ? Py_True : Py_False).inc_ref().ptr();
981     }
982 };
984 NAMESPACE_BEGIN(detail)
985 // Converts a value to the given unsigned type.  If an error occurs, you get back (Unsigned) -1;
986 // otherwise you get back the unsigned long or unsigned long long value cast to (Unsigned).
987 // (The distinction is critically important when casting a returned -1 error value to some other
988 // unsigned type: (A)-1 != (B)-1 when A and B are unsigned types of different sizes).
989 template <typename Unsigned>
990 Unsigned as_unsigned(PyObject *o) {
991     if (sizeof(Unsigned) <= sizeof(unsigned long)
992 #if PY_VERSION_HEX < 0x03000000
993             || PyInt_Check(o)
994 #endif
995     ) {
996         unsigned long v = PyLong_AsUnsignedLong(o);
997         return v == (unsigned long) -1 && PyErr_Occurred() ? (Unsigned) -1 : (Unsigned) v;
998     }
999     else {
1000         unsigned long long v = PyLong_AsUnsignedLongLong(o);
1001         return v == (unsigned long long) -1 && PyErr_Occurred() ? (Unsigned) -1 : (Unsigned) v;
1002     }
1004 NAMESPACE_END(detail)
1006 class int_ : public object {
1007 public:
1008     PYBIND11_OBJECT_CVT(int_, object, PYBIND11_LONG_CHECK, PyNumber_Long)
1009     int_() : object(PyLong_FromLong(0), stolen_t{}) { }
1010     // Allow implicit conversion from C++ integral types:
1011     template <typename T,
1012               detail::enable_if_t<std::is_integral<T>::value, int> = 0>
1013     int_(T value) {
1014         if (sizeof(T) <= sizeof(long)) {
1015             if (std::is_signed<T>::value)
1016                 m_ptr = PyLong_FromLong((long) value);
1017             else
1018                 m_ptr = PyLong_FromUnsignedLong((unsigned long) value);
1019         } else {
1020             if (std::is_signed<T>::value)
1021                 m_ptr = PyLong_FromLongLong((long long) value);
1022             else
1023                 m_ptr = PyLong_FromUnsignedLongLong((unsigned long long) value);
1024         }
1025         if (!m_ptr) pybind11_fail("Could not allocate int object!");
1026     }
1028     template <typename T,
1029               detail::enable_if_t<std::is_integral<T>::value, int> = 0>
1030     operator T() const {
1031         return std::is_unsigned<T>::value
1032             ? detail::as_unsigned<T>(m_ptr)
1033             : sizeof(T) <= sizeof(long)
1034               ? (T) PyLong_AsLong(m_ptr)
1035               : (T) PYBIND11_LONG_AS_LONGLONG(m_ptr);
1036     }
1037 };
1039 class float_ : public object {
1040 public:
1041     PYBIND11_OBJECT_CVT(float_, object, PyFloat_Check, PyNumber_Float)
1042     // Allow implicit conversion from float/double:
1043     float_(float value) : object(PyFloat_FromDouble((double) value), stolen_t{}) {
1044         if (!m_ptr) pybind11_fail("Could not allocate float object!");
1045     }
1046     float_(double value = .0) : object(PyFloat_FromDouble((double) value), stolen_t{}) {
1047         if (!m_ptr) pybind11_fail("Could not allocate float object!");
1048     }
1049     operator float() const { return (float) PyFloat_AsDouble(m_ptr); }
1050     operator double() const { return (double) PyFloat_AsDouble(m_ptr); }
1051 };
1053 class weakref : public object {
1054 public:
1055     PYBIND11_OBJECT_DEFAULT(weakref, object, PyWeakref_Check)
1056     explicit weakref(handle obj, handle callback = {})
1057         : object(PyWeakref_NewRef(obj.ptr(), callback.ptr()), stolen_t{}) {
1058         if (!m_ptr) pybind11_fail("Could not allocate weak reference!");
1059     }
1060 };
1062 class slice : public object {
1063 public:
1064     PYBIND11_OBJECT_DEFAULT(slice, object, PySlice_Check)
1065     slice(ssize_t start_, ssize_t stop_, ssize_t step_) {
1066         int_ start(start_), stop(stop_), step(step_);
1067         m_ptr = PySlice_New(start.ptr(), stop.ptr(), step.ptr());
1068         if (!m_ptr) pybind11_fail("Could not allocate slice object!");
1069     }
1070     bool compute(size_t length, size_t *start, size_t *stop, size_t *step,
1071                  size_t *slicelength) const {
1072         return PySlice_GetIndicesEx((PYBIND11_SLICE_OBJECT *) m_ptr,
1073                                     (ssize_t) length, (ssize_t *) start,
1074                                     (ssize_t *) stop, (ssize_t *) step,
1075                                     (ssize_t *) slicelength) == 0;
1076     }
1077 };
1079 class capsule : public object {
1080 public:
1081     PYBIND11_OBJECT_DEFAULT(capsule, object, PyCapsule_CheckExact)
1082     PYBIND11_DEPRECATED("Use reinterpret_borrow<capsule>() or reinterpret_steal<capsule>()")
1083     capsule(PyObject *ptr, bool is_borrowed) : object(is_borrowed ? object(ptr, borrowed_t{}) : object(ptr, stolen_t{})) { }
1085     explicit capsule(const void *value, const char *name = nullptr, void (*destructor)(PyObject *) = nullptr)
1086         : object(PyCapsule_New(const_cast<void *>(value), name, destructor), stolen_t{}) {
1087         if (!m_ptr)
1088             pybind11_fail("Could not allocate capsule object!");
1089     }
1091     PYBIND11_DEPRECATED("Please pass a destructor that takes a void pointer as input")
1092     capsule(const void *value, void (*destruct)(PyObject *))
1093         : object(PyCapsule_New(const_cast<void*>(value), nullptr, destruct), stolen_t{}) {
1094         if (!m_ptr)
1095             pybind11_fail("Could not allocate capsule object!");
1096     }
1098     capsule(const void *value, void (*destructor)(void *)) {
1099         m_ptr = PyCapsule_New(const_cast<void *>(value), nullptr, [](PyObject *o) {
1100             auto destructor = reinterpret_cast<void (*)(void *)>(PyCapsule_GetContext(o));
1101             void *ptr = PyCapsule_GetPointer(o, nullptr);
1102             destructor(ptr);
1103         });
1105         if (!m_ptr)
1106             pybind11_fail("Could not allocate capsule object!");
1108         if (PyCapsule_SetContext(m_ptr, (void *) destructor) != 0)
1109             pybind11_fail("Could not set capsule context!");
1110     }
1112     capsule(void (*destructor)()) {
1113         m_ptr = PyCapsule_New(reinterpret_cast<void *>(destructor), nullptr, [](PyObject *o) {
1114             auto destructor = reinterpret_cast<void (*)()>(PyCapsule_GetPointer(o, nullptr));
1115             destructor();
1116         });
1118         if (!m_ptr)
1119             pybind11_fail("Could not allocate capsule object!");
1120     }
1122     template <typename T> operator T *() const {
1123         auto name = this->name();
1124         T * result = static_cast<T *>(PyCapsule_GetPointer(m_ptr, name));
1125         if (!result) pybind11_fail("Unable to extract capsule contents!");
1126         return result;
1127     }
1129     const char *name() const { return PyCapsule_GetName(m_ptr); }
1130 };
1132 class tuple : public object {
1133 public:
1134     PYBIND11_OBJECT_CVT(tuple, object, PyTuple_Check, PySequence_Tuple)
1135     explicit tuple(size_t size = 0) : object(PyTuple_New((ssize_t) size), stolen_t{}) {
1136         if (!m_ptr) pybind11_fail("Could not allocate tuple object!");
1137     }
1138     size_t size() const { return (size_t) PyTuple_Size(m_ptr); }
1139     detail::tuple_accessor operator[](size_t index) const { return {*this, index}; }
1140     detail::tuple_iterator begin() const { return {*this, 0}; }
1141     detail::tuple_iterator end() const { return {*this, PyTuple_GET_SIZE(m_ptr)}; }
1142 };
1144 class dict : public object {
1145 public:
1146     PYBIND11_OBJECT_CVT(dict, object, PyDict_Check, raw_dict)
1147     dict() : object(PyDict_New(), stolen_t{}) {
1148         if (!m_ptr) pybind11_fail("Could not allocate dict object!");
1149     }
1150     template <typename... Args,
1151               typename = detail::enable_if_t<detail::all_of<detail::is_keyword_or_ds<Args>...>::value>,
1152               // MSVC workaround: it can't compile an out-of-line definition, so defer the collector
1153               typename collector = detail::deferred_t<detail::unpacking_collector<>, Args...>>
1154     explicit dict(Args &&...args) : dict(collector(std::forward<Args>(args)...).kwargs()) { }
1156     size_t size() const { return (size_t) PyDict_Size(m_ptr); }
1157     detail::dict_iterator begin() const { return {*this, 0}; }
1158     detail::dict_iterator end() const { return {}; }
1159     void clear() const { PyDict_Clear(ptr()); }
1160     bool contains(handle key) const { return PyDict_Contains(ptr(), key.ptr()) == 1; }
1161     bool contains(const char *key) const { return PyDict_Contains(ptr(), pybind11::str(key).ptr()) == 1; }
1163 private:
1164     /// Call the `dict` Python type -- always returns a new reference
1165     static PyObject *raw_dict(PyObject *op) {
1166         if (PyDict_Check(op))
1167             return handle(op).inc_ref().ptr();
1168         return PyObject_CallFunctionObjArgs((PyObject *) &PyDict_Type, op, nullptr);
1169     }
1170 };
1172 class sequence : public object {
1173 public:
1174     PYBIND11_OBJECT_DEFAULT(sequence, object, PySequence_Check)
1175     size_t size() const { return (size_t) PySequence_Size(m_ptr); }
1176     detail::sequence_accessor operator[](size_t index) const { return {*this, index}; }
1177     detail::sequence_iterator begin() const { return {*this, 0}; }
1178     detail::sequence_iterator end() const { return {*this, PySequence_Size(m_ptr)}; }
1179 };
1181 class list : public object {
1182 public:
1183     PYBIND11_OBJECT_CVT(list, object, PyList_Check, PySequence_List)
1184     explicit list(size_t size = 0) : object(PyList_New((ssize_t) size), stolen_t{}) {
1185         if (!m_ptr) pybind11_fail("Could not allocate list object!");
1186     }
1187     size_t size() const { return (size_t) PyList_Size(m_ptr); }
1188     detail::list_accessor operator[](size_t index) const { return {*this, index}; }
1189     detail::list_iterator begin() const { return {*this, 0}; }
1190     detail::list_iterator end() const { return {*this, PyList_GET_SIZE(m_ptr)}; }
1191     template <typename T> void append(T &&val) const {
1192         PyList_Append(m_ptr, detail::object_or_cast(std::forward<T>(val)).ptr());
1193     }
1194 };
1196 class args : public tuple { PYBIND11_OBJECT_DEFAULT(args, tuple, PyTuple_Check) };
1197 class kwargs : public dict { PYBIND11_OBJECT_DEFAULT(kwargs, dict, PyDict_Check)  };
1199 class set : public object {
1200 public:
1201     PYBIND11_OBJECT_CVT(set, object, PySet_Check, PySet_New)
1202     set() : object(PySet_New(nullptr), stolen_t{}) {
1203         if (!m_ptr) pybind11_fail("Could not allocate set object!");
1204     }
1205     size_t size() const { return (size_t) PySet_Size(m_ptr); }
1206     template <typename T> bool add(T &&val) const {
1207         return PySet_Add(m_ptr, detail::object_or_cast(std::forward<T>(val)).ptr()) == 0;
1208     }
1209     void clear() const { PySet_Clear(m_ptr); }
1210 };
1212 class function : public object {
1213 public:
1214     PYBIND11_OBJECT_DEFAULT(function, object, PyCallable_Check)
1215     handle cpp_function() const {
1216         handle fun = detail::get_function(m_ptr);
1217         if (fun && PyCFunction_Check(fun.ptr()))
1218             return fun;
1219         return handle();
1220     }
1221     bool is_cpp_function() const { return (bool) cpp_function(); }
1222 };
1224 class buffer : public object {
1225 public:
1226     PYBIND11_OBJECT_DEFAULT(buffer, object, PyObject_CheckBuffer)
1228     buffer_info request(bool writable = false) {
1229         int flags = PyBUF_STRIDES | PyBUF_FORMAT;
1230         if (writable) flags |= PyBUF_WRITABLE;
1231         Py_buffer *view = new Py_buffer();
1232         if (PyObject_GetBuffer(m_ptr, view, flags) != 0) {
1233             delete view;
1234             throw error_already_set();
1235         }
1236         return buffer_info(view);
1237     }
1238 };
1240 class memoryview : public object {
1241 public:
1242     explicit memoryview(const buffer_info& info) {
1243         static Py_buffer buf { };
1244         // Py_buffer uses signed sizes, strides and shape!..
1245         static std::vector<Py_ssize_t> py_strides { };
1246         static std::vector<Py_ssize_t> py_shape { };
1247         buf.buf = info.ptr;
1248         buf.itemsize = info.itemsize;
1249         buf.format = const_cast<char *>(info.format.c_str());
1250         buf.ndim = (int) info.ndim;
1251         buf.len = info.size;
1252         py_strides.clear();
1253         py_shape.clear();
1254         for (size_t i = 0; i < (size_t) info.ndim; ++i) {
1255             py_strides.push_back(info.strides[i]);
1256             py_shape.push_back(info.shape[i]);
1257         }
1258         buf.strides = py_strides.data();
1259         buf.shape = py_shape.data();
1260         buf.suboffsets = nullptr;
1261         buf.readonly = false;
1262         buf.internal = nullptr;
1264         m_ptr = PyMemoryView_FromBuffer(&buf);
1265         if (!m_ptr)
1266             pybind11_fail("Unable to create memoryview from buffer descriptor");
1267     }
1269     PYBIND11_OBJECT_CVT(memoryview, object, PyMemoryView_Check, PyMemoryView_FromObject)
1270 };
1271 /// @} pytypes
1273 /// \addtogroup python_builtins
1274 /// @{
1275 inline size_t len(handle h) {
1276     ssize_t result = PyObject_Length(h.ptr());
1277     if (result < 0)
1278         pybind11_fail("Unable to compute length of object");
1279     return (size_t) result;
1282 inline str repr(handle h) {
1283     PyObject *str_value = PyObject_Repr(h.ptr());
1284     if (!str_value) throw error_already_set();
1285 #if PY_MAJOR_VERSION < 3
1286     PyObject *unicode = PyUnicode_FromEncodedObject(str_value, "utf-8", nullptr);
1287     Py_XDECREF(str_value); str_value = unicode;
1288     if (!str_value) throw error_already_set();
1289 #endif
1290     return reinterpret_steal<str>(str_value);
1293 inline iterator iter(handle obj) {
1294     PyObject *result = PyObject_GetIter(obj.ptr());
1295     if (!result) { throw error_already_set(); }
1296     return reinterpret_steal<iterator>(result);
1298 /// @} python_builtins
1300 NAMESPACE_BEGIN(detail)
1301 template <typename D> iterator object_api<D>::begin() const { return iter(derived()); }
1302 template <typename D> iterator object_api<D>::end() const { return iterator::sentinel(); }
1303 template <typename D> item_accessor object_api<D>::operator[](handle key) const {
1304     return {derived(), reinterpret_borrow<object>(key)};
1306 template <typename D> item_accessor object_api<D>::operator[](const char *key) const {
1307     return {derived(), pybind11::str(key)};
1309 template <typename D> obj_attr_accessor object_api<D>::attr(handle key) const {
1310     return {derived(), reinterpret_borrow<object>(key)};
1312 template <typename D> str_attr_accessor object_api<D>::attr(const char *key) const {
1313     return {derived(), key};
1315 template <typename D> args_proxy object_api<D>::operator*() const {
1316     return args_proxy(derived().ptr());
1318 template <typename D> template <typename T> bool object_api<D>::contains(T &&item) const {
1319     return attr("__contains__")(std::forward<T>(item)).template cast<bool>();
1322 template <typename D>
1323 pybind11::str object_api<D>::str() const { return pybind11::str(derived()); }
1325 template <typename D>
1326 str_attr_accessor object_api<D>::doc() const { return attr("__doc__"); }
1328 template <typename D>
1329 handle object_api<D>::get_type() const { return (PyObject *) Py_TYPE(derived().ptr()); }
1331 NAMESPACE_END(detail)
1332 NAMESPACE_END(PYBIND11_NAMESPACE)