1 /*
2 pybind11/pytypes.h: Convenience wrapper classes for basic Python types
3
4 Copyright (c) 2016 Wenzel Jakob <wenzel.jakob@epfl.ch>
5
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 */
9
10 #pragma once
11
12 #include "detail/common.h"
13 #include "buffer_info.h"
14 #include <utility>
15 #include <type_traits>
16
17 NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
18
19 /* A few forward declarations */
20 class handle; class object;
21 class str; class iterator;
22 struct arg; struct arg_v;
23
24 NAMESPACE_BEGIN(detail)
25 class args_proxy;
26 inline bool isinstance_generic(handle obj, const std::type_info &tp);
27
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>;
44
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>>;
48
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 {
derived()55 const Derived &derived() const { return static_cast<const Derived &>(*this); }
56
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;
65
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;
75
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;
85
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;
93
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;
96
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()`.
102
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;
112
113 /// Equivalent to ``obj is other`` in Python.
is(object_api const & other)114 bool is(object_api const& other) const { return derived().ptr() == other.derived().ptr(); }
115 /// Equivalent to ``obj is None`` in Python.
is_none()116 bool is_none() const { return derived().ptr() == Py_None; }
117 PYBIND11_DEPRECATED("Use py::str(obj) instead")
118 pybind11::str str() const;
119
120 /// Get or set the object's docstring, i.e. ``obj.__doc__``.
121 str_attr_accessor doc() const;
122
123 /// Return the object's current reference count
ref_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 };
128
NAMESPACE_END(detail)129 NAMESPACE_END(detail)
130
131 /** \rst
132 Holds a reference to a Python object (no reference counting)
133
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.
137
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*
148
149 /// Return the underlying ``PyObject *`` pointer
150 PyObject *ptr() const { return m_ptr; }
151 PyObject *&ptr() { return m_ptr; }
152
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; }
159
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; }
166
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 };
187
188 /** \rst
189 Holds a reference to a Python object (with reference counting)
190
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>()")
object(handle h,bool is_borrowed)202 object(handle h, bool is_borrowed) : handle(h) { if (is_borrowed) inc_ref(); }
203 /// Copy constructor; always increases the reference count
object(const object & o)204 object(const object &o) : handle(o) { inc_ref(); }
205 /// Move constructor; steals the object from ``other`` and preserves its reference count
object(object && other)206 object(object &&other) noexcept { m_ptr = other.m_ptr; other.m_ptr = nullptr; }
207 /// Destructor; automatically calls `handle::dec_ref()`
~object()208 ~object() { dec_ref(); }
209
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 */
release()215 handle release() {
216 PyObject *tmp = m_ptr;
217 m_ptr = nullptr;
218 return handle(tmp);
219 }
220
221 object& operator=(const object &other) {
222 other.inc_ref();
223 dec_ref();
224 m_ptr = other.m_ptr;
225 return *this;
226 }
227
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 }
237
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() &&;
242
243 protected:
244 // Tags for choosing constructors from raw PyObject *
245 struct borrowed_t { };
246 struct stolen_t { };
247
248 template <typename T> friend T reinterpret_borrow(handle);
249 template <typename T> friend T reinterpret_steal(handle);
250
251 public:
252 // Only accessible from derived classes and the reinterpret_* functions
object(handle h,borrowed_t)253 object(handle h, borrowed_t) : handle(h) { inc_ref(); }
object(handle h,stolen_t)254 object(handle h, stolen_t) : handle(h) { }
255 };
256
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.
262
263 .. code-block:: cpp
264
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 */
reinterpret_borrow(handle h)270 template <typename T> T reinterpret_borrow(handle h) { return {h, object::borrowed_t{}}; }
271
272 /** \rst
273 Like `reinterpret_borrow`, but steals the reference.
274
275 .. code-block:: cpp
276
277 PyObject *p = PyObject_Str(obj);
278 py::str s = reinterpret_steal<py::str>(p); // <-- `p` must be already be a `str`
279 \endrst */
reinterpret_steal(handle h)280 template <typename T> T reinterpret_steal(handle h) { return {h, object::stolen_t{}}; }
281
282 NAMESPACE_BEGIN(detail)
283 inline std::string error_string();
NAMESPACE_END(detail)284 NAMESPACE_END(detail)
285
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 }
297
298 inline ~error_already_set();
299
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()); }
304
305 // Does nothing; provided for backwards compatibility.
306 PYBIND11_DEPRECATED("Use of error_already_set.clear() is deprecated")
307 void clear() {}
308
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()); }
313
314 private:
315 object type, value, trace;
316 };
317
318 /** \defgroup python_builtins _
319 Unless stated otherwise, the following C++ functions behave the same
320 as their Python counterparts.
321 */
322
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>
isinstance(handle obj)329 bool isinstance(handle obj) { return T::check_(obj); }
330
331 template <typename T, detail::enable_if_t<!std::is_base_of<object, T>::value, int> = 0>
isinstance(handle obj)332 bool isinstance(handle obj) { return detail::isinstance_generic(obj, typeid(T)); }
333
334 template <> inline bool isinstance<handle>(handle obj) = delete;
335 template <> inline bool isinstance<object>(handle obj) { return obj.ptr() != nullptr; }
336
337 /// \ingroup python_builtins
338 /// Return true if ``obj`` is an instance of the ``type``.
isinstance(handle obj,handle 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;
344 }
345
346 /// \addtogroup python_builtins
347 /// @{
hasattr(handle obj,handle name)348 inline bool hasattr(handle obj, handle name) {
349 return PyObject_HasAttr(obj.ptr(), name.ptr()) == 1;
350 }
351
hasattr(handle obj,const char * name)352 inline bool hasattr(handle obj, const char *name) {
353 return PyObject_HasAttrString(obj.ptr(), name) == 1;
354 }
355
getattr(handle obj,handle name)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);
360 }
361
getattr(handle obj,const char * name)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);
366 }
367
getattr(handle obj,handle name,handle default_)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 }
375 }
376
getattr(handle obj,const char * name,handle default_)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 }
384 }
385
setattr(handle obj,handle name,handle value)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(); }
388 }
389
setattr(handle obj,const char * name,handle value)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(); }
392 }
393
hash(handle obj)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;
398 }
399
400 /// @} python_builtins
401
NAMESPACE_BEGIN(detail)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;
414 }
415
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
object_or_cast(PyObject * ptr)425 inline handle object_or_cast(PyObject *ptr) { return ptr; }
426
427
428 template <typename Policy>
429 class accessor : public object_api<accessor<Policy>> {
430 using key_type = typename Policy::key_type;
431
432 public:
accessor(handle obj,key_type key)433 accessor(handle obj, key_type key) : obj(obj), key(std::move(key)) { }
434 accessor(const accessor &) = default;
435 accessor(accessor &&) = default;
436
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)); }
441
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 }
448
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 }
460
object()461 operator object() const { return get_cache(); }
ptr()462 PyObject *ptr() const { return get_cache().ptr(); }
cast()463 template <typename T> T cast() const { return get_cache().template cast<T>(); }
464
465 private:
get_cache()466 object &get_cache() const {
467 if (!cache) { cache = Policy::get(obj, key); }
468 return cache;
469 }
470
471 private:
472 handle obj;
473 key_type key;
474 mutable object cache;
475 };
476
477 NAMESPACE_BEGIN(accessor_policies)
478 struct obj_attr {
479 using key_type = object;
getobj_attr480 static object get(handle obj, handle key) { return getattr(obj, key); }
setobj_attr481 static void set(handle obj, handle key, handle val) { setattr(obj, key, val); }
482 };
483
484 struct str_attr {
485 using key_type = const char *;
getstr_attr486 static object get(handle obj, const char *key) { return getattr(obj, key); }
setstr_attr487 static void set(handle obj, const char *key, handle val) { setattr(obj, key, val); }
488 };
489
490 struct generic_item {
491 using key_type = object;
492
getgeneric_item493 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 }
498
setgeneric_item499 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 };
503
504 struct sequence_item {
505 using key_type = size_t;
506
getsequence_item507 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 }
512
setsequence_item513 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 };
520
521 struct list_item {
522 using key_type = size_t;
523
getlist_item524 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 }
529
setlist_item530 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 };
537
538 struct tuple_item {
539 using key_type = size_t;
540
gettuple_item541 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 }
546
settuple_item547 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 };
NAMESPACE_END(accessor_policies)554 NAMESPACE_END(accessor_policies)
555
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;
560
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;
567
568 generic_iterator() = default;
569 generic_iterator(handle seq, ssize_t index) : Policy(seq, index) { }
570
571 reference operator*() const { return Policy::dereference(); }
572 reference operator[](difference_type n) const { return *(*this + n); }
573 pointer operator->() const { return **this; }
574
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; }
581
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); }
586
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 };
594
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;
600
arrow_proxyarrow_proxy601 arrow_proxy(T &&value) : value(std::move(value)) { }
602 T *operator->() const { return &value; }
603 };
604
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>;
612
sequence_fast_readonly(handle obj,ssize_t n)613 sequence_fast_readonly(handle obj, ssize_t n) : ptr(PySequence_Fast_ITEMS(obj.ptr()) + n) { }
614
dereference()615 reference dereference() const { return *ptr; }
increment()616 void increment() { ++ptr; }
decrement()617 void decrement() { --ptr; }
advance(ssize_t n)618 void advance(ssize_t n) { ptr += n; }
equal(const sequence_fast_readonly & b)619 bool equal(const sequence_fast_readonly &b) const { return ptr == b.ptr; }
distance_to(const sequence_fast_readonly & b)620 ssize_t distance_to(const sequence_fast_readonly &b) const { return ptr - b.ptr; }
621
622 private:
623 PyObject **ptr;
624 };
625
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>;
633
sequence_slow_readwrite(handle obj,ssize_t index)634 sequence_slow_readwrite(handle obj, ssize_t index) : obj(obj), index(index) { }
635
dereference()636 reference dereference() const { return {obj, static_cast<size_t>(index)}; }
increment()637 void increment() { ++index; }
decrement()638 void decrement() { --index; }
advance(ssize_t n)639 void advance(ssize_t n) { index += n; }
equal(const sequence_slow_readwrite & b)640 bool equal(const sequence_slow_readwrite &b) const { return index == b.index; }
distance_to(const sequence_slow_readwrite & b)641 ssize_t distance_to(const sequence_slow_readwrite &b) const { return index - b.index; }
642
643 private:
644 handle obj;
645 ssize_t index;
646 };
647
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>;
655
656 dict_readonly() = default;
dict_readonly(handle obj,ssize_t pos)657 dict_readonly(handle obj, ssize_t pos) : obj(obj), pos(pos) { increment(); }
658
dereference()659 reference dereference() const { return {key, value}; }
increment()660 void increment() { if (!PyDict_Next(obj.ptr(), &pos, &key, &value)) { pos = -1; } }
equal(const dict_readonly & b)661 bool equal(const dict_readonly &b) const { return pos == b.pos; }
662
663 private:
664 handle obj;
665 PyObject *key, *value;
666 ssize_t pos = -1;
667 };
668 NAMESPACE_END(iterator_policies)
669
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
677
678 using sequence_iterator = generic_iterator<iterator_policies::sequence_slow_readwrite>;
679 using dict_iterator = generic_iterator<iterator_policies::dict_readonly>;
680
PyIterable_Check(PyObject * obj)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 }
690 }
691
PyNone_Check(PyObject * o)692 inline bool PyNone_Check(PyObject *o) { return o == Py_None; }
693
PyUnicode_Check_Permissive(PyObject * o)694 inline bool PyUnicode_Check_Permissive(PyObject *o) { return PyUnicode_Check(o) || PYBIND11_BYTES_CHECK(o); }
695
696 class kwargs_proxy : public handle {
697 public:
kwargs_proxy(handle h)698 explicit kwargs_proxy(handle h) : handle(h) { }
699 };
700
701 class args_proxy : public handle {
702 public:
args_proxy(handle h)703 explicit args_proxy(handle h) : handle(h) { }
704 kwargs_proxy operator*() const { return kwargs_proxy(*this); }
705 };
706
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>;
715
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;
721
NAMESPACE_END(detail)722 NAMESPACE_END(detail)
723
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()); }
737
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)) { }
749
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)) { }
755
756 #define PYBIND11_OBJECT_DEFAULT(Name, Parent, CheckFun) \
757 PYBIND11_OBJECT(Name, Parent, CheckFun) \
758 Name() : Parent() { }
759
760 /// \addtogroup pytypes
761 /// @{
762
763 /** \rst
764 Wraps a Python iterator so that it can also be used as a C++ input iterator
765
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 *;
778
779 PYBIND11_OBJECT_DEFAULT(iterator, object, PyIter_Check)
780
781 iterator& operator++() {
782 advance();
783 return *this;
784 }
785
786 iterator operator++(int) {
787 auto rv = *this;
788 advance();
789 return rv;
790 }
791
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 }
799
800 pointer operator->() const { operator*(); return &value; }
801
802 /** \rst
803 The value which marks the end of the iteration. ``it == iterator::sentinel()``
804 is equivalent to catching ``StopIteration`` in Python.
805
806 .. code-block:: cpp
807
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 {}; }
816
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(); }
819
820 private:
821 void advance() {
822 value = reinterpret_steal<object>(PyIter_Next(m_ptr));
823 if (PyErr_Occurred()) { throw error_already_set(); }
824 }
825
826 private:
827 object value = {};
828 };
829
830 class iterable : public object {
831 public:
832 PYBIND11_OBJECT_DEFAULT(iterable, object, detail::PyIterable_Check)
833 };
834
835 class bytes;
836
837 class str : public object {
838 public:
PYBIND11_OBJECT_CVT(str,object,detail::PyUnicode_Check_Permissive,raw_str)839 PYBIND11_OBJECT_CVT(str, object, detail::PyUnicode_Check_Permissive, raw_str)
840
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 }
845
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 = "")
object(PyUnicode_FromString (c),stolen_t{})848 : object(PyUnicode_FromString(c), stolen_t{}) {
849 if (!m_ptr) pybind11_fail("Could not allocate string object!");
850 }
851
str(const std::string & s)852 str(const std::string &s) : str(s.data(), s.size()) { }
853
854 explicit str(const bytes &b);
855
856 /** \rst
857 Return a string representation of the object. This is analogous to
858 the ``str()`` function in Python.
859 \endrst */
str(handle h)860 explicit str(handle h) : object(raw_str(h.ptr()), stolen_t{}) { }
861
string()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 }
875
876 template <typename... Args>
format(Args &&...args)877 str format(Args &&...args) const {
878 return attr("format")(std::forward<Args>(args)...);
879 }
880
881 private:
882 /// Return string representation -- always returns a new reference, even if already a str
raw_str(PyObject * op)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
894
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}; }
900 }
901
902 /// \addtogroup pytypes
903 /// @{
904 class bytes : public object {
905 public:
PYBIND11_OBJECT(bytes,object,PYBIND11_BYTES_CHECK)906 PYBIND11_OBJECT(bytes, object, PYBIND11_BYTES_CHECK)
907
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 }
913
bytes(const char * c,size_t n)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 }
918
919 // Allow implicit conversion:
bytes(const std::string & s)920 bytes(const std::string &s) : bytes(s.data(), s.size()) { }
921
922 explicit bytes(const pybind11::str &s);
923
string()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 };
932
bytes(const pybind11::str & s)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();
948 }
949
str(const bytes & b)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();
959 }
960
961 class none : public object {
962 public:
PYBIND11_OBJECT(none,object,detail::PyNone_Check)963 PYBIND11_OBJECT(none, object, detail::PyNone_Check)
964 none() : object(Py_None, borrowed_t{}) { }
965 };
966
967 class bool_ : public object {
968 public:
PYBIND11_OBJECT_CVT(bool_,object,PyBool_Check,raw_bool)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`:
bool_(bool value)972 bool_(bool value) : object(value ? Py_True : Py_False, borrowed_t{}) { }
973 operator bool() const { return m_ptr && PyLong_AsLong(m_ptr) != 0; }
974
975 private:
976 /// Return the truth value of an object -- always returns a new reference
raw_bool(PyObject * op)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 };
983
NAMESPACE_BEGIN(detail)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 }
1003 }
NAMESPACE_END(detail)1004 NAMESPACE_END(detail)
1005
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 }
1027
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 };
1038
1039 class float_ : public object {
1040 public:
PYBIND11_OBJECT_CVT(float_,object,PyFloat_Check,PyNumber_Float)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 };
1052
1053 class weakref : public object {
1054 public:
PYBIND11_OBJECT_DEFAULT(weakref,object,PyWeakref_Check)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 };
1061
1062 class slice : public object {
1063 public:
PYBIND11_OBJECT_DEFAULT(slice,object,PySlice_Check)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 }
compute(size_t length,size_t * start,size_t * stop,size_t * step,size_t * slicelength)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 };
1078
1079 class capsule : public object {
1080 public:
PYBIND11_OBJECT_DEFAULT(capsule,object,PyCapsule_CheckExact)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{})) { }
1084
1085 explicit capsule(const void *value, const char *name = nullptr, void (*destructor)(PyObject *) = nullptr)
object(PyCapsule_New (const_cast<void * > (value),name,destructor),stolen_t{})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 }
1090
1091 PYBIND11_DEPRECATED("Please pass a destructor that takes a void pointer as input")
capsule(const void * value,void (* destruct)(PyObject *))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 }
1097
capsule(const void * value,void (* destructor)(void *))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 });
1104
1105 if (!m_ptr)
1106 pybind11_fail("Could not allocate capsule object!");
1107
1108 if (PyCapsule_SetContext(m_ptr, (void *) destructor) != 0)
1109 pybind11_fail("Could not set capsule context!");
1110 }
1111
capsule(void (* destructor)())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 });
1117
1118 if (!m_ptr)
1119 pybind11_fail("Could not allocate capsule object!");
1120 }
1121
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 }
1128
name()1129 const char *name() const { return PyCapsule_GetName(m_ptr); }
1130 };
1131
1132 class tuple : public object {
1133 public:
PYBIND11_OBJECT_CVT(tuple,object,PyTuple_Check,PySequence_Tuple)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 }
size()1138 size_t size() const { return (size_t) PyTuple_Size(m_ptr); }
1139 detail::tuple_accessor operator[](size_t index) const { return {*this, index}; }
begin()1140 detail::tuple_iterator begin() const { return {*this, 0}; }
end()1141 detail::tuple_iterator end() const { return {*this, PyTuple_GET_SIZE(m_ptr)}; }
1142 };
1143
1144 class dict : public object {
1145 public:
PYBIND11_OBJECT_CVT(dict,object,PyDict_Check,raw_dict)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...>>
dict(Args &&...args)1154 explicit dict(Args &&...args) : dict(collector(std::forward<Args>(args)...).kwargs()) { }
1155
size()1156 size_t size() const { return (size_t) PyDict_Size(m_ptr); }
begin()1157 detail::dict_iterator begin() const { return {*this, 0}; }
end()1158 detail::dict_iterator end() const { return {}; }
clear()1159 void clear() const { PyDict_Clear(ptr()); }
contains(handle key)1160 bool contains(handle key) const { return PyDict_Contains(ptr(), key.ptr()) == 1; }
contains(const char * key)1161 bool contains(const char *key) const { return PyDict_Contains(ptr(), pybind11::str(key).ptr()) == 1; }
1162
1163 private:
1164 /// Call the `dict` Python type -- always returns a new reference
raw_dict(PyObject * op)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 };
1171
1172 class sequence : public object {
1173 public:
PYBIND11_OBJECT_DEFAULT(sequence,object,PySequence_Check)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}; }
begin()1177 detail::sequence_iterator begin() const { return {*this, 0}; }
end()1178 detail::sequence_iterator end() const { return {*this, PySequence_Size(m_ptr)}; }
1179 };
1180
1181 class list : public object {
1182 public:
PYBIND11_OBJECT_CVT(list,object,PyList_Check,PySequence_List)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 }
size()1187 size_t size() const { return (size_t) PyList_Size(m_ptr); }
1188 detail::list_accessor operator[](size_t index) const { return {*this, index}; }
begin()1189 detail::list_iterator begin() const { return {*this, 0}; }
end()1190 detail::list_iterator end() const { return {*this, PyList_GET_SIZE(m_ptr)}; }
append(T && val)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 };
1195
1196 class args : public tuple { PYBIND11_OBJECT_DEFAULT(args, tuple, PyTuple_Check) };
1197 class kwargs : public dict { PYBIND11_OBJECT_DEFAULT(kwargs, dict, PyDict_Check) };
1198
1199 class set : public object {
1200 public:
PYBIND11_OBJECT_CVT(set,object,PySet_Check,PySet_New)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 }
size()1205 size_t size() const { return (size_t) PySet_Size(m_ptr); }
add(T && val)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 }
clear()1209 void clear() const { PySet_Clear(m_ptr); }
1210 };
1211
1212 class function : public object {
1213 public:
PYBIND11_OBJECT_DEFAULT(function,object,PyCallable_Check)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 }
is_cpp_function()1221 bool is_cpp_function() const { return (bool) cpp_function(); }
1222 };
1223
1224 class buffer : public object {
1225 public:
PYBIND11_OBJECT_DEFAULT(buffer,object,PyObject_CheckBuffer)1226 PYBIND11_OBJECT_DEFAULT(buffer, object, PyObject_CheckBuffer)
1227
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 };
1239
1240 class memoryview : public object {
1241 public:
memoryview(const buffer_info & info)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;
1263
1264 m_ptr = PyMemoryView_FromBuffer(&buf);
1265 if (!m_ptr)
1266 pybind11_fail("Unable to create memoryview from buffer descriptor");
1267 }
1268
1269 PYBIND11_OBJECT_CVT(memoryview, object, PyMemoryView_Check, PyMemoryView_FromObject)
1270 };
1271 /// @} pytypes
1272
1273 /// \addtogroup python_builtins
1274 /// @{
len(handle h)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;
1280 }
1281
repr(handle h)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);
1291 }
1292
iter(handle obj)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);
1297 }
1298 /// @} python_builtins
1299
NAMESPACE_BEGIN(detail)1300 NAMESPACE_BEGIN(detail)
1301 template <typename D> iterator object_api<D>::begin() const { return iter(derived()); }
end()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)};
1305 }
1306 template <typename D> item_accessor object_api<D>::operator[](const char *key) const {
1307 return {derived(), pybind11::str(key)};
1308 }
attr(handle key)1309 template <typename D> obj_attr_accessor object_api<D>::attr(handle key) const {
1310 return {derived(), reinterpret_borrow<object>(key)};
1311 }
attr(const char * key)1312 template <typename D> str_attr_accessor object_api<D>::attr(const char *key) const {
1313 return {derived(), key};
1314 }
1315 template <typename D> args_proxy object_api<D>::operator*() const {
1316 return args_proxy(derived().ptr());
1317 }
contains(T && item)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>();
1320 }
1321
1322 template <typename D>
str()1323 pybind11::str object_api<D>::str() const { return pybind11::str(derived()); }
1324
1325 template <typename D>
doc()1326 str_attr_accessor object_api<D>::doc() const { return attr("__doc__"); }
1327
1328 template <typename D>
get_type()1329 handle object_api<D>::get_type() const { return (PyObject *) Py_TYPE(derived().ptr()); }
1330
1331 NAMESPACE_END(detail)
1332 NAMESPACE_END(PYBIND11_NAMESPACE)
1333