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.
12 #include "detail/common.h"
13 #include "buffer_info.h"
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)
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 {
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>>;
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``.
53 template <typename Derived>
54 class object_api : public pyobject_tag {
55 const Derived &derived() const { return static_cast<const Derived &>(*this); }
59 Return an iterator equivalent to calling ``iter()`` in Python. The object
60 must be a collection which supports the iteration protocol.
62 iterator begin() const;
63 /// Return a sentinel which ends iteration.
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__``.
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;
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``.
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;
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`.
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;
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.
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 /// Equivalent to obj == other in Python
118 bool equal(object_api const &other) const { return rich_compare(other, Py_EQ); }
119 bool not_equal(object_api const &other) const { return rich_compare(other, Py_NE); }
120 bool operator<(object_api const &other) const { return rich_compare(other, Py_LT); }
121 bool operator<=(object_api const &other) const { return rich_compare(other, Py_LE); }
122 bool operator>(object_api const &other) const { return rich_compare(other, Py_GT); }
123 bool operator>=(object_api const &other) const { return rich_compare(other, Py_GE); }
125 object operator-() const;
126 object operator~() const;
127 object operator+(object_api const &other) const;
128 object operator+=(object_api const &other) const;
129 object operator-(object_api const &other) const;
130 object operator-=(object_api const &other) const;
131 object operator*(object_api const &other) const;
132 object operator*=(object_api const &other) const;
133 object operator/(object_api const &other) const;
134 object operator/=(object_api const &other) const;
135 object operator|(object_api const &other) const;
136 object operator|=(object_api const &other) const;
137 object operator&(object_api const &other) const;
138 object operator&=(object_api const &other) const;
139 object operator^(object_api const &other) const;
140 object operator^=(object_api const &other) const;
141 object operator<<(object_api const &other) const;
142 object operator<<=(object_api const &other) const;
143 object operator>>(object_api const &other) const;
144 object operator>>=(object_api const &other) const;
146 PYBIND11_DEPRECATED("Use py::str(obj) instead")
147 pybind11::str str() const;
149 /// Get or set the object's docstring, i.e. ``obj.__doc__``.
150 str_attr_accessor doc() const;
152 /// Return the object's current reference count
153 int ref_count() const { return static_cast<int>(Py_REFCNT(derived().ptr())); }
154 /// Return a handle to the Python type object underlying the instance
155 handle get_type() const;
158 bool rich_compare(object_api const &other, int value) const;
161 NAMESPACE_END(detail)
164 Holds a reference to a Python object (no reference counting)
166 The `handle` class is a thin wrapper around an arbitrary Python object (i.e. a
167 ``PyObject *`` in Python's C API). It does not perform any automatic reference
168 counting and merely provides a basic C++ interface to various Python API functions.
171 The `object` class inherits from `handle` and adds automatic reference
174 class handle : public detail::object_api<handle> {
176 /// The default constructor creates a handle with a ``nullptr``-valued pointer
178 /// Creates a ``handle`` from the given raw Python object pointer
179 handle(PyObject *ptr) : m_ptr(ptr) { } // Allow implicit conversion from PyObject*
181 /// Return the underlying ``PyObject *`` pointer
182 PyObject *ptr() const { return m_ptr; }
183 PyObject *&ptr() { return m_ptr; }
186 Manually increase the reference count of the Python object. Usually, it is
187 preferable to use the `object` class which derives from `handle` and calls
188 this function automatically. Returns a reference to itself.
190 const handle& inc_ref() const & { Py_XINCREF(m_ptr); return *this; }
193 Manually decrease the reference count of the Python object. Usually, it is
194 preferable to use the `object` class which derives from `handle` and calls
195 this function automatically. Returns a reference to itself.
197 const handle& dec_ref() const & { Py_XDECREF(m_ptr); return *this; }
200 Attempt to cast the Python object into the given C++ type. A `cast_error`
201 will be throw upon failure.
203 template <typename T> T cast() const;
204 /// Return ``true`` when the `handle` wraps a valid Python object
205 explicit operator bool() const { return m_ptr != nullptr; }
207 Deprecated: Check that the underlying pointers are the same.
208 Equivalent to ``obj1 is obj2`` in Python.
210 PYBIND11_DEPRECATED("Use obj1.is(obj2) instead")
211 bool operator==(const handle &h) const { return m_ptr == h.m_ptr; }
212 PYBIND11_DEPRECATED("Use !obj1.is(obj2) instead")
213 bool operator!=(const handle &h) const { return m_ptr != h.m_ptr; }
214 PYBIND11_DEPRECATED("Use handle::operator bool() instead")
215 bool check() const { return m_ptr != nullptr; }
217 PyObject *m_ptr = nullptr;
221 Holds a reference to a Python object (with reference counting)
223 Like `handle`, the `object` class is a thin wrapper around an arbitrary Python
224 object (i.e. a ``PyObject *`` in Python's C API). In contrast to `handle`, it
225 optionally increases the object's reference count upon construction, and it
226 *always* decreases the reference count when the `object` instance goes out of
227 scope and is destructed. When using `object` instances consistently, it is much
228 easier to get reference counting right at the first attempt.
230 class object : public handle {
233 PYBIND11_DEPRECATED("Use reinterpret_borrow<object>() or reinterpret_steal<object>()")
234 object(handle h, bool is_borrowed) : handle(h) { if (is_borrowed) inc_ref(); }
235 /// Copy constructor; always increases the reference count
236 object(const object &o) : handle(o) { inc_ref(); }
237 /// Move constructor; steals the object from ``other`` and preserves its reference count
238 object(object &&other) noexcept { m_ptr = other.m_ptr; other.m_ptr = nullptr; }
239 /// Destructor; automatically calls `handle::dec_ref()`
240 ~object() { dec_ref(); }
243 Resets the internal pointer to ``nullptr`` without without decreasing the
244 object's reference count. The function returns a raw handle to the original
248 PyObject *tmp = m_ptr;
253 object& operator=(const object &other) {
260 object& operator=(object &&other) noexcept {
261 if (this != &other) {
264 other.m_ptr = nullptr;
270 // Calling cast() on an object lvalue just copies (via handle::cast)
271 template <typename T> T cast() const &;
272 // Calling on an object rvalue does a move, if needed and/or possible
273 template <typename T> T cast() &&;
276 // Tags for choosing constructors from raw PyObject *
277 struct borrowed_t { };
280 template <typename T> friend T reinterpret_borrow(handle);
281 template <typename T> friend T reinterpret_steal(handle);
284 // Only accessible from derived classes and the reinterpret_* functions
285 object(handle h, borrowed_t) : handle(h) { inc_ref(); }
286 object(handle h, stolen_t) : handle(h) { }
290 Declare that a `handle` or ``PyObject *`` is a certain type and borrow the reference.
291 The target type ``T`` must be `object` or one of its derived classes. The function
292 doesn't do any conversions or checks. It's up to the user to make sure that the
293 target type is correct.
297 PyObject *p = PyList_GetItem(obj, index);
298 py::object o = reinterpret_borrow<py::object>(p);
300 py::tuple t = reinterpret_borrow<py::tuple>(p); // <-- `p` must be already be a `tuple`
302 template <typename T> T reinterpret_borrow(handle h) { return {h, object::borrowed_t{}}; }
305 Like `reinterpret_borrow`, but steals the reference.
309 PyObject *p = PyObject_Str(obj);
310 py::str s = reinterpret_steal<py::str>(p); // <-- `p` must be already be a `str`
312 template <typename T> T reinterpret_steal(handle h) { return {h, object::stolen_t{}}; }
314 NAMESPACE_BEGIN(detail)
315 inline std::string error_string();
316 NAMESPACE_END(detail)
318 /// Fetch and hold an error which was already set in Python. An instance of this is typically
319 /// thrown to propagate python-side errors back through C++ which can either be caught manually or
320 /// else falls back to the function dispatcher (which then raises the captured error back to
322 class error_already_set : public std::runtime_error {
324 /// Constructs a new exception from the current Python error indicator, if any. The current
325 /// Python error indicator will be cleared.
326 error_already_set() : std::runtime_error(detail::error_string()) {
327 PyErr_Fetch(&m_type.ptr(), &m_value.ptr(), &m_trace.ptr());
330 error_already_set(const error_already_set &) = default;
331 error_already_set(error_already_set &&) = default;
333 inline ~error_already_set();
335 /// Give the currently-held error back to Python, if any. If there is currently a Python error
336 /// already set it is cleared first. After this call, the current object no longer stores the
337 /// error variables (but the `.what()` string is still available).
338 void restore() { PyErr_Restore(m_type.release().ptr(), m_value.release().ptr(), m_trace.release().ptr()); }
340 // Does nothing; provided for backwards compatibility.
341 PYBIND11_DEPRECATED("Use of error_already_set.clear() is deprecated")
344 /// Check if the currently trapped error type matches the given Python exception class (or a
345 /// subclass thereof). May also be passed a tuple to search for any exception class matches in
347 bool matches(handle exc) const { return PyErr_GivenExceptionMatches(m_type.ptr(), exc.ptr()); }
349 const object& type() const { return m_type; }
350 const object& value() const { return m_value; }
351 const object& trace() const { return m_trace; }
354 object m_type, m_value, m_trace;
357 /** \defgroup python_builtins _
358 Unless stated otherwise, the following C++ functions behave the same
359 as their Python counterparts.
362 /** \ingroup python_builtins
364 Return true if ``obj`` is an instance of ``T``. Type ``T`` must be a subclass of
365 `object` or a class which was exposed to Python as ``py::class_<T>``.
367 template <typename T, detail::enable_if_t<std::is_base_of<object, T>::value, int> = 0>
368 bool isinstance(handle obj) { return T::check_(obj); }
370 template <typename T, detail::enable_if_t<!std::is_base_of<object, T>::value, int> = 0>
371 bool isinstance(handle obj) { return detail::isinstance_generic(obj, typeid(T)); }
373 template <> inline bool isinstance<handle>(handle obj) = delete;
374 template <> inline bool isinstance<object>(handle obj) { return obj.ptr() != nullptr; }
376 /// \ingroup python_builtins
377 /// Return true if ``obj`` is an instance of the ``type``.
378 inline bool isinstance(handle obj, handle type) {
379 const auto result = PyObject_IsInstance(obj.ptr(), type.ptr());
381 throw error_already_set();
385 /// \addtogroup python_builtins
387 inline bool hasattr(handle obj, handle name) {
388 return PyObject_HasAttr(obj.ptr(), name.ptr()) == 1;
391 inline bool hasattr(handle obj, const char *name) {
392 return PyObject_HasAttrString(obj.ptr(), name) == 1;
395 inline void delattr(handle obj, handle name) {
396 if (PyObject_DelAttr(obj.ptr(), name.ptr()) != 0) { throw error_already_set(); }
399 inline void delattr(handle obj, const char *name) {
400 if (PyObject_DelAttrString(obj.ptr(), name) != 0) { throw error_already_set(); }
403 inline object getattr(handle obj, handle name) {
404 PyObject *result = PyObject_GetAttr(obj.ptr(), name.ptr());
405 if (!result) { throw error_already_set(); }
406 return reinterpret_steal<object>(result);
409 inline object getattr(handle obj, const char *name) {
410 PyObject *result = PyObject_GetAttrString(obj.ptr(), name);
411 if (!result) { throw error_already_set(); }
412 return reinterpret_steal<object>(result);
415 inline object getattr(handle obj, handle name, handle default_) {
416 if (PyObject *result = PyObject_GetAttr(obj.ptr(), name.ptr())) {
417 return reinterpret_steal<object>(result);
420 return reinterpret_borrow<object>(default_);
424 inline object getattr(handle obj, const char *name, handle default_) {
425 if (PyObject *result = PyObject_GetAttrString(obj.ptr(), name)) {
426 return reinterpret_steal<object>(result);
429 return reinterpret_borrow<object>(default_);
433 inline void setattr(handle obj, handle name, handle value) {
434 if (PyObject_SetAttr(obj.ptr(), name.ptr(), value.ptr()) != 0) { throw error_already_set(); }
437 inline void setattr(handle obj, const char *name, handle value) {
438 if (PyObject_SetAttrString(obj.ptr(), name, value.ptr()) != 0) { throw error_already_set(); }
441 inline ssize_t hash(handle obj) {
442 auto h = PyObject_Hash(obj.ptr());
443 if (h == -1) { throw error_already_set(); }
447 /// @} python_builtins
449 NAMESPACE_BEGIN(detail)
450 inline handle get_function(handle value) {
452 #if PY_MAJOR_VERSION >= 3
453 if (PyInstanceMethod_Check(value.ptr()))
454 value = PyInstanceMethod_GET_FUNCTION(value.ptr());
457 if (PyMethod_Check(value.ptr()))
458 value = PyMethod_GET_FUNCTION(value.ptr());
463 // Helper aliases/functions to support implicit casting of values given to python accessors/methods.
464 // When given a pyobject, this simply returns the pyobject as-is; for other C++ type, the value goes
465 // through pybind11::cast(obj) to convert it to an `object`.
466 template <typename T, enable_if_t<is_pyobject<T>::value, int> = 0>
467 auto object_or_cast(T &&o) -> decltype(std::forward<T>(o)) { return std::forward<T>(o); }
468 // The following casting version is implemented in cast.h:
469 template <typename T, enable_if_t<!is_pyobject<T>::value, int> = 0>
470 object object_or_cast(T &&o);
471 // Match a PyObject*, which we want to convert directly to handle via its converting constructor
472 inline handle object_or_cast(PyObject *ptr) { return ptr; }
474 template <typename Policy>
475 class accessor : public object_api<accessor<Policy>> {
476 using key_type = typename Policy::key_type;
479 accessor(handle obj, key_type key) : obj(obj), key(std::move(key)) { }
480 accessor(const accessor &) = default;
481 accessor(accessor &&) = default;
483 // accessor overload required to override default assignment operator (templates are not allowed
484 // to replace default compiler-generated assignments).
485 void operator=(const accessor &a) && { std::move(*this).operator=(handle(a)); }
486 void operator=(const accessor &a) & { operator=(handle(a)); }
488 template <typename T> void operator=(T &&value) && {
489 Policy::set(obj, key, object_or_cast(std::forward<T>(value)));
491 template <typename T> void operator=(T &&value) & {
492 get_cache() = reinterpret_borrow<object>(object_or_cast(std::forward<T>(value)));
495 template <typename T = Policy>
496 PYBIND11_DEPRECATED("Use of obj.attr(...) as bool is deprecated in favor of pybind11::hasattr(obj, ...)")
497 explicit operator enable_if_t<std::is_same<T, accessor_policies::str_attr>::value ||
498 std::is_same<T, accessor_policies::obj_attr>::value, bool>() const {
499 return hasattr(obj, key);
501 template <typename T = Policy>
502 PYBIND11_DEPRECATED("Use of obj[key] as bool is deprecated in favor of obj.contains(key)")
503 explicit operator enable_if_t<std::is_same<T, accessor_policies::generic_item>::value, bool>() const {
504 return obj.contains(key);
507 operator object() const { return get_cache(); }
508 PyObject *ptr() const { return get_cache().ptr(); }
509 template <typename T> T cast() const { return get_cache().template cast<T>(); }
512 object &get_cache() const {
513 if (!cache) { cache = Policy::get(obj, key); }
520 mutable object cache;
523 NAMESPACE_BEGIN(accessor_policies)
525 using key_type = object;
526 static object get(handle obj, handle key) { return getattr(obj, key); }
527 static void set(handle obj, handle key, handle val) { setattr(obj, key, val); }
531 using key_type = const char *;
532 static object get(handle obj, const char *key) { return getattr(obj, key); }
533 static void set(handle obj, const char *key, handle val) { setattr(obj, key, val); }
536 struct generic_item {
537 using key_type = object;
539 static object get(handle obj, handle key) {
540 PyObject *result = PyObject_GetItem(obj.ptr(), key.ptr());
541 if (!result) { throw error_already_set(); }
542 return reinterpret_steal<object>(result);
545 static void set(handle obj, handle key, handle val) {
546 if (PyObject_SetItem(obj.ptr(), key.ptr(), val.ptr()) != 0) { throw error_already_set(); }
550 struct sequence_item {
551 using key_type = size_t;
553 static object get(handle obj, size_t index) {
554 PyObject *result = PySequence_GetItem(obj.ptr(), static_cast<ssize_t>(index));
555 if (!result) { throw error_already_set(); }
556 return reinterpret_steal<object>(result);
559 static void set(handle obj, size_t index, handle val) {
560 // PySequence_SetItem does not steal a reference to 'val'
561 if (PySequence_SetItem(obj.ptr(), static_cast<ssize_t>(index), val.ptr()) != 0) {
562 throw error_already_set();
568 using key_type = size_t;
570 static object get(handle obj, size_t index) {
571 PyObject *result = PyList_GetItem(obj.ptr(), static_cast<ssize_t>(index));
572 if (!result) { throw error_already_set(); }
573 return reinterpret_borrow<object>(result);
576 static void set(handle obj, size_t index, handle val) {
577 // PyList_SetItem steals a reference to 'val'
578 if (PyList_SetItem(obj.ptr(), static_cast<ssize_t>(index), val.inc_ref().ptr()) != 0) {
579 throw error_already_set();
585 using key_type = size_t;
587 static object get(handle obj, size_t index) {
588 PyObject *result = PyTuple_GetItem(obj.ptr(), static_cast<ssize_t>(index));
589 if (!result) { throw error_already_set(); }
590 return reinterpret_borrow<object>(result);
593 static void set(handle obj, size_t index, handle val) {
594 // PyTuple_SetItem steals a reference to 'val'
595 if (PyTuple_SetItem(obj.ptr(), static_cast<ssize_t>(index), val.inc_ref().ptr()) != 0) {
596 throw error_already_set();
600 NAMESPACE_END(accessor_policies)
602 /// STL iterator template used for tuple, list, sequence and dict
603 template <typename Policy>
604 class generic_iterator : public Policy {
605 using It = generic_iterator;
608 using difference_type = ssize_t;
609 using iterator_category = typename Policy::iterator_category;
610 using value_type = typename Policy::value_type;
611 using reference = typename Policy::reference;
612 using pointer = typename Policy::pointer;
614 generic_iterator() = default;
615 generic_iterator(handle seq, ssize_t index) : Policy(seq, index) { }
617 reference operator*() const { return Policy::dereference(); }
618 reference operator[](difference_type n) const { return *(*this + n); }
619 pointer operator->() const { return **this; }
621 It &operator++() { Policy::increment(); return *this; }
622 It operator++(int) { auto copy = *this; Policy::increment(); return copy; }
623 It &operator--() { Policy::decrement(); return *this; }
624 It operator--(int) { auto copy = *this; Policy::decrement(); return copy; }
625 It &operator+=(difference_type n) { Policy::advance(n); return *this; }
626 It &operator-=(difference_type n) { Policy::advance(-n); return *this; }
628 friend It operator+(const It &a, difference_type n) { auto copy = a; return copy += n; }
629 friend It operator+(difference_type n, const It &b) { return b + n; }
630 friend It operator-(const It &a, difference_type n) { auto copy = a; return copy -= n; }
631 friend difference_type operator-(const It &a, const It &b) { return a.distance_to(b); }
633 friend bool operator==(const It &a, const It &b) { return a.equal(b); }
634 friend bool operator!=(const It &a, const It &b) { return !(a == b); }
635 friend bool operator< (const It &a, const It &b) { return b - a > 0; }
636 friend bool operator> (const It &a, const It &b) { return b < a; }
637 friend bool operator>=(const It &a, const It &b) { return !(a < b); }
638 friend bool operator<=(const It &a, const It &b) { return !(a > b); }
641 NAMESPACE_BEGIN(iterator_policies)
642 /// Quick proxy class needed to implement ``operator->`` for iterators which can't return pointers
643 template <typename T>
647 arrow_proxy(T &&value) : value(std::move(value)) { }
648 T *operator->() const { return &value; }
651 /// Lightweight iterator policy using just a simple pointer: see ``PySequence_Fast_ITEMS``
652 class sequence_fast_readonly {
654 using iterator_category = std::random_access_iterator_tag;
655 using value_type = handle;
656 using reference = const handle;
657 using pointer = arrow_proxy<const handle>;
659 sequence_fast_readonly(handle obj, ssize_t n) : ptr(PySequence_Fast_ITEMS(obj.ptr()) + n) { }
661 reference dereference() const { return *ptr; }
662 void increment() { ++ptr; }
663 void decrement() { --ptr; }
664 void advance(ssize_t n) { ptr += n; }
665 bool equal(const sequence_fast_readonly &b) const { return ptr == b.ptr; }
666 ssize_t distance_to(const sequence_fast_readonly &b) const { return ptr - b.ptr; }
672 /// Full read and write access using the sequence protocol: see ``detail::sequence_accessor``
673 class sequence_slow_readwrite {
675 using iterator_category = std::random_access_iterator_tag;
676 using value_type = object;
677 using reference = sequence_accessor;
678 using pointer = arrow_proxy<const sequence_accessor>;
680 sequence_slow_readwrite(handle obj, ssize_t index) : obj(obj), index(index) { }
682 reference dereference() const { return {obj, static_cast<size_t>(index)}; }
683 void increment() { ++index; }
684 void decrement() { --index; }
685 void advance(ssize_t n) { index += n; }
686 bool equal(const sequence_slow_readwrite &b) const { return index == b.index; }
687 ssize_t distance_to(const sequence_slow_readwrite &b) const { return index - b.index; }
694 /// Python's dictionary protocol permits this to be a forward iterator
695 class dict_readonly {
697 using iterator_category = std::forward_iterator_tag;
698 using value_type = std::pair<handle, handle>;
699 using reference = const value_type;
700 using pointer = arrow_proxy<const value_type>;
702 dict_readonly() = default;
703 dict_readonly(handle obj, ssize_t pos) : obj(obj), pos(pos) { increment(); }
705 reference dereference() const { return {key, value}; }
706 void increment() { if (!PyDict_Next(obj.ptr(), &pos, &key, &value)) { pos = -1; } }
707 bool equal(const dict_readonly &b) const { return pos == b.pos; }
711 PyObject *key = nullptr, *value = nullptr;
714 NAMESPACE_END(iterator_policies)
716 #if !defined(PYPY_VERSION)
717 using tuple_iterator = generic_iterator<iterator_policies::sequence_fast_readonly>;
718 using list_iterator = generic_iterator<iterator_policies::sequence_fast_readonly>;
720 using tuple_iterator = generic_iterator<iterator_policies::sequence_slow_readwrite>;
721 using list_iterator = generic_iterator<iterator_policies::sequence_slow_readwrite>;
724 using sequence_iterator = generic_iterator<iterator_policies::sequence_slow_readwrite>;
725 using dict_iterator = generic_iterator<iterator_policies::dict_readonly>;
727 inline bool PyIterable_Check(PyObject *obj) {
728 PyObject *iter = PyObject_GetIter(obj);
738 inline bool PyNone_Check(PyObject *o) { return o == Py_None; }
739 #if PY_MAJOR_VERSION >= 3
740 inline bool PyEllipsis_Check(PyObject *o) { return o == Py_Ellipsis; }
743 inline bool PyUnicode_Check_Permissive(PyObject *o) { return PyUnicode_Check(o) || PYBIND11_BYTES_CHECK(o); }
745 inline bool PyStaticMethod_Check(PyObject *o) { return o->ob_type == &PyStaticMethod_Type; }
747 class kwargs_proxy : public handle {
749 explicit kwargs_proxy(handle h) : handle(h) { }
752 class args_proxy : public handle {
754 explicit args_proxy(handle h) : handle(h) { }
755 kwargs_proxy operator*() const { return kwargs_proxy(*this); }
758 /// Python argument categories (using PEP 448 terms)
759 template <typename T> using is_keyword = std::is_base_of<arg, T>;
760 template <typename T> using is_s_unpacking = std::is_same<args_proxy, T>; // * unpacking
761 template <typename T> using is_ds_unpacking = std::is_same<kwargs_proxy, T>; // ** unpacking
762 template <typename T> using is_positional = satisfies_none_of<T,
763 is_keyword, is_s_unpacking, is_ds_unpacking
765 template <typename T> using is_keyword_or_ds = satisfies_any_of<T, is_keyword, is_ds_unpacking>;
767 // Call argument collector forward declarations
768 template <return_value_policy policy = return_value_policy::automatic_reference>
769 class simple_collector;
770 template <return_value_policy policy = return_value_policy::automatic_reference>
771 class unpacking_collector;
773 NAMESPACE_END(detail)
775 // TODO: After the deprecated constructors are removed, this macro can be simplified by
776 // inheriting ctors: `using Parent::Parent`. It's not an option right now because
777 // the `using` statement triggers the parent deprecation warning even if the ctor
779 #define PYBIND11_OBJECT_COMMON(Name, Parent, CheckFun) \
781 PYBIND11_DEPRECATED("Use reinterpret_borrow<"#Name">() or reinterpret_steal<"#Name">()") \
782 Name(handle h, bool is_borrowed) : Parent(is_borrowed ? Parent(h, borrowed_t{}) : Parent(h, stolen_t{})) { } \
783 Name(handle h, borrowed_t) : Parent(h, borrowed_t{}) { } \
784 Name(handle h, stolen_t) : Parent(h, stolen_t{}) { } \
785 PYBIND11_DEPRECATED("Use py::isinstance<py::python_type>(obj) instead") \
786 bool check() const { return m_ptr != nullptr && (bool) CheckFun(m_ptr); } \
787 static bool check_(handle h) { return h.ptr() != nullptr && CheckFun(h.ptr()); }
789 #define PYBIND11_OBJECT_CVT(Name, Parent, CheckFun, ConvertFun) \
790 PYBIND11_OBJECT_COMMON(Name, Parent, CheckFun) \
791 /* This is deliberately not 'explicit' to allow implicit conversion from object: */ \
792 Name(const object &o) \
793 : Parent(check_(o) ? o.inc_ref().ptr() : ConvertFun(o.ptr()), stolen_t{}) \
794 { if (!m_ptr) throw error_already_set(); } \
796 : Parent(check_(o) ? o.release().ptr() : ConvertFun(o.ptr()), stolen_t{}) \
797 { if (!m_ptr) throw error_already_set(); } \
798 template <typename Policy_> \
799 Name(const ::pybind11::detail::accessor<Policy_> &a) : Name(object(a)) { }
801 #define PYBIND11_OBJECT(Name, Parent, CheckFun) \
802 PYBIND11_OBJECT_COMMON(Name, Parent, CheckFun) \
803 /* This is deliberately not 'explicit' to allow implicit conversion from object: */ \
804 Name(const object &o) : Parent(o) { } \
805 Name(object &&o) : Parent(std::move(o)) { }
807 #define PYBIND11_OBJECT_DEFAULT(Name, Parent, CheckFun) \
808 PYBIND11_OBJECT(Name, Parent, CheckFun) \
809 Name() : Parent() { }
811 /// \addtogroup pytypes
815 Wraps a Python iterator so that it can also be used as a C++ input iterator
817 Caveat: copying an iterator does not (and cannot) clone the internal
818 state of the Python iterable. This also applies to the post-increment
819 operator. This iterator should only be used to retrieve the current
820 value using ``operator*()``.
822 class iterator : public object {
824 using iterator_category = std::input_iterator_tag;
825 using difference_type = ssize_t;
826 using value_type = handle;
827 using reference = const handle;
828 using pointer = const handle *;
830 PYBIND11_OBJECT_DEFAULT(iterator, object, PyIter_Check)
832 iterator& operator++() {
837 iterator operator++(int) {
843 reference operator*() const {
844 if (m_ptr && !value.ptr()) {
845 auto& self = const_cast<iterator &>(*this);
851 pointer operator->() const { operator*(); return &value; }
854 The value which marks the end of the iteration. ``it == iterator::sentinel()``
855 is equivalent to catching ``StopIteration`` in Python.
859 void foo(py::iterator it) {
860 while (it != py::iterator::sentinel()) {
866 static iterator sentinel() { return {}; }
868 friend bool operator==(const iterator &a, const iterator &b) { return a->ptr() == b->ptr(); }
869 friend bool operator!=(const iterator &a, const iterator &b) { return a->ptr() != b->ptr(); }
873 value = reinterpret_steal<object>(PyIter_Next(m_ptr));
874 if (PyErr_Occurred()) { throw error_already_set(); }
881 class iterable : public object {
883 PYBIND11_OBJECT_DEFAULT(iterable, object, detail::PyIterable_Check)
888 class str : public object {
890 PYBIND11_OBJECT_CVT(str, object, detail::PyUnicode_Check_Permissive, raw_str)
892 str(const char *c, size_t n)
893 : object(PyUnicode_FromStringAndSize(c, (ssize_t) n), stolen_t{}) {
894 if (!m_ptr) pybind11_fail("Could not allocate string object!");
897 // 'explicit' is explicitly omitted from the following constructors to allow implicit conversion to py::str from C++ string-like objects
898 str(const char *c = "")
899 : object(PyUnicode_FromString(c), stolen_t{}) {
900 if (!m_ptr) pybind11_fail("Could not allocate string object!");
903 str(const std::string &s) : str(s.data(), s.size()) { }
905 explicit str(const bytes &b);
908 Return a string representation of the object. This is analogous to
909 the ``str()`` function in Python.
911 explicit str(handle h) : object(raw_str(h.ptr()), stolen_t{}) { }
913 operator std::string() const {
915 if (PyUnicode_Check(m_ptr)) {
916 temp = reinterpret_steal<object>(PyUnicode_AsUTF8String(m_ptr));
918 pybind11_fail("Unable to extract string contents! (encoding issue)");
922 if (PYBIND11_BYTES_AS_STRING_AND_SIZE(temp.ptr(), &buffer, &length))
923 pybind11_fail("Unable to extract string contents! (invalid type)");
924 return std::string(buffer, (size_t) length);
927 template <typename... Args>
928 str format(Args &&...args) const {
929 return attr("format")(std::forward<Args>(args)...);
933 /// Return string representation -- always returns a new reference, even if already a str
934 static PyObject *raw_str(PyObject *op) {
935 PyObject *str_value = PyObject_Str(op);
936 #if PY_MAJOR_VERSION < 3
937 if (!str_value) throw error_already_set();
938 PyObject *unicode = PyUnicode_FromEncodedObject(str_value, "utf-8", nullptr);
939 Py_XDECREF(str_value); str_value = unicode;
946 inline namespace literals {
948 String literal version of `str`
950 inline str operator"" _s(const char *s, size_t size) { return {s, size}; }
953 /// \addtogroup pytypes
955 class bytes : public object {
957 PYBIND11_OBJECT(bytes, object, PYBIND11_BYTES_CHECK)
959 // Allow implicit conversion:
960 bytes(const char *c = "")
961 : object(PYBIND11_BYTES_FROM_STRING(c), stolen_t{}) {
962 if (!m_ptr) pybind11_fail("Could not allocate bytes object!");
965 bytes(const char *c, size_t n)
966 : object(PYBIND11_BYTES_FROM_STRING_AND_SIZE(c, (ssize_t) n), stolen_t{}) {
967 if (!m_ptr) pybind11_fail("Could not allocate bytes object!");
970 // Allow implicit conversion:
971 bytes(const std::string &s) : bytes(s.data(), s.size()) { }
973 explicit bytes(const pybind11::str &s);
975 operator std::string() const {
978 if (PYBIND11_BYTES_AS_STRING_AND_SIZE(m_ptr, &buffer, &length))
979 pybind11_fail("Unable to extract bytes contents!");
980 return std::string(buffer, (size_t) length);
984 inline bytes::bytes(const pybind11::str &s) {
986 if (PyUnicode_Check(s.ptr())) {
987 temp = reinterpret_steal<object>(PyUnicode_AsUTF8String(s.ptr()));
989 pybind11_fail("Unable to extract string contents! (encoding issue)");
993 if (PYBIND11_BYTES_AS_STRING_AND_SIZE(temp.ptr(), &buffer, &length))
994 pybind11_fail("Unable to extract string contents! (invalid type)");
995 auto obj = reinterpret_steal<object>(PYBIND11_BYTES_FROM_STRING_AND_SIZE(buffer, length));
997 pybind11_fail("Could not allocate bytes object!");
998 m_ptr = obj.release().ptr();
1001 inline str::str(const bytes& b) {
1004 if (PYBIND11_BYTES_AS_STRING_AND_SIZE(b.ptr(), &buffer, &length))
1005 pybind11_fail("Unable to extract bytes contents!");
1006 auto obj = reinterpret_steal<object>(PyUnicode_FromStringAndSize(buffer, (ssize_t) length));
1008 pybind11_fail("Could not allocate string object!");
1009 m_ptr = obj.release().ptr();
1012 class none : public object {
1014 PYBIND11_OBJECT(none, object, detail::PyNone_Check)
1015 none() : object(Py_None, borrowed_t{}) { }
1018 #if PY_MAJOR_VERSION >= 3
1019 class ellipsis : public object {
1021 PYBIND11_OBJECT(ellipsis, object, detail::PyEllipsis_Check)
1022 ellipsis() : object(Py_Ellipsis, borrowed_t{}) { }
1026 class bool_ : public object {
1028 PYBIND11_OBJECT_CVT(bool_, object, PyBool_Check, raw_bool)
1029 bool_() : object(Py_False, borrowed_t{}) { }
1030 // Allow implicit conversion from and to `bool`:
1031 bool_(bool value) : object(value ? Py_True : Py_False, borrowed_t{}) { }
1032 operator bool() const { return m_ptr && PyLong_AsLong(m_ptr) != 0; }
1035 /// Return the truth value of an object -- always returns a new reference
1036 static PyObject *raw_bool(PyObject *op) {
1037 const auto value = PyObject_IsTrue(op);
1038 if (value == -1) return nullptr;
1039 return handle(value ? Py_True : Py_False).inc_ref().ptr();
1043 NAMESPACE_BEGIN(detail)
1044 // Converts a value to the given unsigned type. If an error occurs, you get back (Unsigned) -1;
1045 // otherwise you get back the unsigned long or unsigned long long value cast to (Unsigned).
1046 // (The distinction is critically important when casting a returned -1 error value to some other
1047 // unsigned type: (A)-1 != (B)-1 when A and B are unsigned types of different sizes).
1048 template <typename Unsigned>
1049 Unsigned as_unsigned(PyObject *o) {
1050 if (sizeof(Unsigned) <= sizeof(unsigned long)
1051 #if PY_VERSION_HEX < 0x03000000
1055 unsigned long v = PyLong_AsUnsignedLong(o);
1056 return v == (unsigned long) -1 && PyErr_Occurred() ? (Unsigned) -1 : (Unsigned) v;
1059 unsigned long long v = PyLong_AsUnsignedLongLong(o);
1060 return v == (unsigned long long) -1 && PyErr_Occurred() ? (Unsigned) -1 : (Unsigned) v;
1063 NAMESPACE_END(detail)
1065 class int_ : public object {
1067 PYBIND11_OBJECT_CVT(int_, object, PYBIND11_LONG_CHECK, PyNumber_Long)
1068 int_() : object(PyLong_FromLong(0), stolen_t{}) { }
1069 // Allow implicit conversion from C++ integral types:
1070 template <typename T,
1071 detail::enable_if_t<std::is_integral<T>::value, int> = 0>
1073 if (sizeof(T) <= sizeof(long)) {
1074 if (std::is_signed<T>::value)
1075 m_ptr = PyLong_FromLong((long) value);
1077 m_ptr = PyLong_FromUnsignedLong((unsigned long) value);
1079 if (std::is_signed<T>::value)
1080 m_ptr = PyLong_FromLongLong((long long) value);
1082 m_ptr = PyLong_FromUnsignedLongLong((unsigned long long) value);
1084 if (!m_ptr) pybind11_fail("Could not allocate int object!");
1087 template <typename T,
1088 detail::enable_if_t<std::is_integral<T>::value, int> = 0>
1089 operator T() const {
1090 return std::is_unsigned<T>::value
1091 ? detail::as_unsigned<T>(m_ptr)
1092 : sizeof(T) <= sizeof(long)
1093 ? (T) PyLong_AsLong(m_ptr)
1094 : (T) PYBIND11_LONG_AS_LONGLONG(m_ptr);
1098 class float_ : public object {
1100 PYBIND11_OBJECT_CVT(float_, object, PyFloat_Check, PyNumber_Float)
1101 // Allow implicit conversion from float/double:
1102 float_(float value) : object(PyFloat_FromDouble((double) value), stolen_t{}) {
1103 if (!m_ptr) pybind11_fail("Could not allocate float object!");
1105 float_(double value = .0) : object(PyFloat_FromDouble((double) value), stolen_t{}) {
1106 if (!m_ptr) pybind11_fail("Could not allocate float object!");
1108 operator float() const { return (float) PyFloat_AsDouble(m_ptr); }
1109 operator double() const { return (double) PyFloat_AsDouble(m_ptr); }
1112 class weakref : public object {
1114 PYBIND11_OBJECT_DEFAULT(weakref, object, PyWeakref_Check)
1115 explicit weakref(handle obj, handle callback = {})
1116 : object(PyWeakref_NewRef(obj.ptr(), callback.ptr()), stolen_t{}) {
1117 if (!m_ptr) pybind11_fail("Could not allocate weak reference!");
1121 class slice : public object {
1123 PYBIND11_OBJECT_DEFAULT(slice, object, PySlice_Check)
1124 slice(ssize_t start_, ssize_t stop_, ssize_t step_) {
1125 int_ start(start_), stop(stop_), step(step_);
1126 m_ptr = PySlice_New(start.ptr(), stop.ptr(), step.ptr());
1127 if (!m_ptr) pybind11_fail("Could not allocate slice object!");
1129 bool compute(size_t length, size_t *start, size_t *stop, size_t *step,
1130 size_t *slicelength) const {
1131 return PySlice_GetIndicesEx((PYBIND11_SLICE_OBJECT *) m_ptr,
1132 (ssize_t) length, (ssize_t *) start,
1133 (ssize_t *) stop, (ssize_t *) step,
1134 (ssize_t *) slicelength) == 0;
1136 bool compute(ssize_t length, ssize_t *start, ssize_t *stop, ssize_t *step,
1137 ssize_t *slicelength) const {
1138 return PySlice_GetIndicesEx((PYBIND11_SLICE_OBJECT *) m_ptr,
1145 class capsule : public object {
1147 PYBIND11_OBJECT_DEFAULT(capsule, object, PyCapsule_CheckExact)
1148 PYBIND11_DEPRECATED("Use reinterpret_borrow<capsule>() or reinterpret_steal<capsule>()")
1149 capsule(PyObject *ptr, bool is_borrowed) : object(is_borrowed ? object(ptr, borrowed_t{}) : object(ptr, stolen_t{})) { }
1151 explicit capsule(const void *value, const char *name = nullptr, void (*destructor)(PyObject *) = nullptr)
1152 : object(PyCapsule_New(const_cast<void *>(value), name, destructor), stolen_t{}) {
1154 pybind11_fail("Could not allocate capsule object!");
1157 PYBIND11_DEPRECATED("Please pass a destructor that takes a void pointer as input")
1158 capsule(const void *value, void (*destruct)(PyObject *))
1159 : object(PyCapsule_New(const_cast<void*>(value), nullptr, destruct), stolen_t{}) {
1161 pybind11_fail("Could not allocate capsule object!");
1164 capsule(const void *value, void (*destructor)(void *)) {
1165 m_ptr = PyCapsule_New(const_cast<void *>(value), nullptr, [](PyObject *o) {
1166 auto destructor = reinterpret_cast<void (*)(void *)>(PyCapsule_GetContext(o));
1167 void *ptr = PyCapsule_GetPointer(o, nullptr);
1172 pybind11_fail("Could not allocate capsule object!");
1174 if (PyCapsule_SetContext(m_ptr, (void *) destructor) != 0)
1175 pybind11_fail("Could not set capsule context!");
1178 capsule(void (*destructor)()) {
1179 m_ptr = PyCapsule_New(reinterpret_cast<void *>(destructor), nullptr, [](PyObject *o) {
1180 auto destructor = reinterpret_cast<void (*)()>(PyCapsule_GetPointer(o, nullptr));
1185 pybind11_fail("Could not allocate capsule object!");
1188 template <typename T> operator T *() const {
1189 auto name = this->name();
1190 T * result = static_cast<T *>(PyCapsule_GetPointer(m_ptr, name));
1191 if (!result) pybind11_fail("Unable to extract capsule contents!");
1195 const char *name() const { return PyCapsule_GetName(m_ptr); }
1198 class tuple : public object {
1200 PYBIND11_OBJECT_CVT(tuple, object, PyTuple_Check, PySequence_Tuple)
1201 explicit tuple(size_t size = 0) : object(PyTuple_New((ssize_t) size), stolen_t{}) {
1202 if (!m_ptr) pybind11_fail("Could not allocate tuple object!");
1204 size_t size() const { return (size_t) PyTuple_Size(m_ptr); }
1205 bool empty() const { return size() == 0; }
1206 detail::tuple_accessor operator[](size_t index) const { return {*this, index}; }
1207 detail::item_accessor operator[](handle h) const { return object::operator[](h); }
1208 detail::tuple_iterator begin() const { return {*this, 0}; }
1209 detail::tuple_iterator end() const { return {*this, PyTuple_GET_SIZE(m_ptr)}; }
1212 class dict : public object {
1214 PYBIND11_OBJECT_CVT(dict, object, PyDict_Check, raw_dict)
1215 dict() : object(PyDict_New(), stolen_t{}) {
1216 if (!m_ptr) pybind11_fail("Could not allocate dict object!");
1218 template <typename... Args,
1219 typename = detail::enable_if_t<detail::all_of<detail::is_keyword_or_ds<Args>...>::value>,
1220 // MSVC workaround: it can't compile an out-of-line definition, so defer the collector
1221 typename collector = detail::deferred_t<detail::unpacking_collector<>, Args...>>
1222 explicit dict(Args &&...args) : dict(collector(std::forward<Args>(args)...).kwargs()) { }
1224 size_t size() const { return (size_t) PyDict_Size(m_ptr); }
1225 bool empty() const { return size() == 0; }
1226 detail::dict_iterator begin() const { return {*this, 0}; }
1227 detail::dict_iterator end() const { return {}; }
1228 void clear() const { PyDict_Clear(ptr()); }
1229 template <typename T> bool contains(T &&key) const {
1230 return PyDict_Contains(m_ptr, detail::object_or_cast(std::forward<T>(key)).ptr()) == 1;
1234 /// Call the `dict` Python type -- always returns a new reference
1235 static PyObject *raw_dict(PyObject *op) {
1236 if (PyDict_Check(op))
1237 return handle(op).inc_ref().ptr();
1238 return PyObject_CallFunctionObjArgs((PyObject *) &PyDict_Type, op, nullptr);
1242 class sequence : public object {
1244 PYBIND11_OBJECT_DEFAULT(sequence, object, PySequence_Check)
1245 size_t size() const { return (size_t) PySequence_Size(m_ptr); }
1246 bool empty() const { return size() == 0; }
1247 detail::sequence_accessor operator[](size_t index) const { return {*this, index}; }
1248 detail::item_accessor operator[](handle h) const { return object::operator[](h); }
1249 detail::sequence_iterator begin() const { return {*this, 0}; }
1250 detail::sequence_iterator end() const { return {*this, PySequence_Size(m_ptr)}; }
1253 class list : public object {
1255 PYBIND11_OBJECT_CVT(list, object, PyList_Check, PySequence_List)
1256 explicit list(size_t size = 0) : object(PyList_New((ssize_t) size), stolen_t{}) {
1257 if (!m_ptr) pybind11_fail("Could not allocate list object!");
1259 size_t size() const { return (size_t) PyList_Size(m_ptr); }
1260 bool empty() const { return size() == 0; }
1261 detail::list_accessor operator[](size_t index) const { return {*this, index}; }
1262 detail::item_accessor operator[](handle h) const { return object::operator[](h); }
1263 detail::list_iterator begin() const { return {*this, 0}; }
1264 detail::list_iterator end() const { return {*this, PyList_GET_SIZE(m_ptr)}; }
1265 template <typename T> void append(T &&val) const {
1266 PyList_Append(m_ptr, detail::object_or_cast(std::forward<T>(val)).ptr());
1268 template <typename T> void insert(size_t index, T &&val) const {
1269 PyList_Insert(m_ptr, static_cast<ssize_t>(index),
1270 detail::object_or_cast(std::forward<T>(val)).ptr());
1274 class args : public tuple { PYBIND11_OBJECT_DEFAULT(args, tuple, PyTuple_Check) };
1275 class kwargs : public dict { PYBIND11_OBJECT_DEFAULT(kwargs, dict, PyDict_Check) };
1277 class set : public object {
1279 PYBIND11_OBJECT_CVT(set, object, PySet_Check, PySet_New)
1280 set() : object(PySet_New(nullptr), stolen_t{}) {
1281 if (!m_ptr) pybind11_fail("Could not allocate set object!");
1283 size_t size() const { return (size_t) PySet_Size(m_ptr); }
1284 bool empty() const { return size() == 0; }
1285 template <typename T> bool add(T &&val) const {
1286 return PySet_Add(m_ptr, detail::object_or_cast(std::forward<T>(val)).ptr()) == 0;
1288 void clear() const { PySet_Clear(m_ptr); }
1289 template <typename T> bool contains(T &&val) const {
1290 return PySet_Contains(m_ptr, detail::object_or_cast(std::forward<T>(val)).ptr()) == 1;
1294 class function : public object {
1296 PYBIND11_OBJECT_DEFAULT(function, object, PyCallable_Check)
1297 handle cpp_function() const {
1298 handle fun = detail::get_function(m_ptr);
1299 if (fun && PyCFunction_Check(fun.ptr()))
1303 bool is_cpp_function() const { return (bool) cpp_function(); }
1306 class staticmethod : public object {
1308 PYBIND11_OBJECT_CVT(staticmethod, object, detail::PyStaticMethod_Check, PyStaticMethod_New)
1311 class buffer : public object {
1313 PYBIND11_OBJECT_DEFAULT(buffer, object, PyObject_CheckBuffer)
1315 buffer_info request(bool writable = false) const {
1316 int flags = PyBUF_STRIDES | PyBUF_FORMAT;
1317 if (writable) flags |= PyBUF_WRITABLE;
1318 Py_buffer *view = new Py_buffer();
1319 if (PyObject_GetBuffer(m_ptr, view, flags) != 0) {
1321 throw error_already_set();
1323 return buffer_info(view);
1327 class memoryview : public object {
1329 explicit memoryview(const buffer_info& info) {
1330 static Py_buffer buf { };
1331 // Py_buffer uses signed sizes, strides and shape!..
1332 static std::vector<Py_ssize_t> py_strides { };
1333 static std::vector<Py_ssize_t> py_shape { };
1335 buf.itemsize = info.itemsize;
1336 buf.format = const_cast<char *>(info.format.c_str());
1337 buf.ndim = (int) info.ndim;
1338 buf.len = info.size;
1341 for (size_t i = 0; i < (size_t) info.ndim; ++i) {
1342 py_strides.push_back(info.strides[i]);
1343 py_shape.push_back(info.shape[i]);
1345 buf.strides = py_strides.data();
1346 buf.shape = py_shape.data();
1347 buf.suboffsets = nullptr;
1348 buf.readonly = info.readonly;
1349 buf.internal = nullptr;
1351 m_ptr = PyMemoryView_FromBuffer(&buf);
1353 pybind11_fail("Unable to create memoryview from buffer descriptor");
1356 PYBIND11_OBJECT_CVT(memoryview, object, PyMemoryView_Check, PyMemoryView_FromObject)
1360 /// \addtogroup python_builtins
1362 inline size_t len(handle h) {
1363 ssize_t result = PyObject_Length(h.ptr());
1365 pybind11_fail("Unable to compute length of object");
1366 return (size_t) result;
1369 inline size_t len_hint(handle h) {
1370 #if PY_VERSION_HEX >= 0x03040000
1371 ssize_t result = PyObject_LengthHint(h.ptr(), 0);
1373 ssize_t result = PyObject_Length(h.ptr());
1376 // Sometimes a length can't be determined at all (eg generators)
1377 // In which case simply return 0
1381 return (size_t) result;
1384 inline str repr(handle h) {
1385 PyObject *str_value = PyObject_Repr(h.ptr());
1386 if (!str_value) throw error_already_set();
1387 #if PY_MAJOR_VERSION < 3
1388 PyObject *unicode = PyUnicode_FromEncodedObject(str_value, "utf-8", nullptr);
1389 Py_XDECREF(str_value); str_value = unicode;
1390 if (!str_value) throw error_already_set();
1392 return reinterpret_steal<str>(str_value);
1395 inline iterator iter(handle obj) {
1396 PyObject *result = PyObject_GetIter(obj.ptr());
1397 if (!result) { throw error_already_set(); }
1398 return reinterpret_steal<iterator>(result);
1400 /// @} python_builtins
1402 NAMESPACE_BEGIN(detail)
1403 template <typename D> iterator object_api<D>::begin() const { return iter(derived()); }
1404 template <typename D> iterator object_api<D>::end() const { return iterator::sentinel(); }
1405 template <typename D> item_accessor object_api<D>::operator[](handle key) const {
1406 return {derived(), reinterpret_borrow<object>(key)};
1408 template <typename D> item_accessor object_api<D>::operator[](const char *key) const {
1409 return {derived(), pybind11::str(key)};
1411 template <typename D> obj_attr_accessor object_api<D>::attr(handle key) const {
1412 return {derived(), reinterpret_borrow<object>(key)};
1414 template <typename D> str_attr_accessor object_api<D>::attr(const char *key) const {
1415 return {derived(), key};
1417 template <typename D> args_proxy object_api<D>::operator*() const {
1418 return args_proxy(derived().ptr());
1420 template <typename D> template <typename T> bool object_api<D>::contains(T &&item) const {
1421 return attr("__contains__")(std::forward<T>(item)).template cast<bool>();
1424 template <typename D>
1425 pybind11::str object_api<D>::str() const { return pybind11::str(derived()); }
1427 template <typename D>
1428 str_attr_accessor object_api<D>::doc() const { return attr("__doc__"); }
1430 template <typename D>
1431 handle object_api<D>::get_type() const { return (PyObject *) Py_TYPE(derived().ptr()); }
1433 template <typename D>
1434 bool object_api<D>::rich_compare(object_api const &other, int value) const {
1435 int rv = PyObject_RichCompareBool(derived().ptr(), other.derived().ptr(), value);
1437 throw error_already_set();
1441 #define PYBIND11_MATH_OPERATOR_UNARY(op, fn) \
1442 template <typename D> object object_api<D>::op() const { \
1443 object result = reinterpret_steal<object>(fn(derived().ptr())); \
1444 if (!result.ptr()) \
1445 throw error_already_set(); \
1449 #define PYBIND11_MATH_OPERATOR_BINARY(op, fn) \
1450 template <typename D> \
1451 object object_api<D>::op(object_api const &other) const { \
1452 object result = reinterpret_steal<object>( \
1453 fn(derived().ptr(), other.derived().ptr())); \
1454 if (!result.ptr()) \
1455 throw error_already_set(); \
1459 PYBIND11_MATH_OPERATOR_UNARY (operator~, PyNumber_Invert)
1460 PYBIND11_MATH_OPERATOR_UNARY (operator-, PyNumber_Negative)
1461 PYBIND11_MATH_OPERATOR_BINARY(operator+, PyNumber_Add)
1462 PYBIND11_MATH_OPERATOR_BINARY(operator+=, PyNumber_InPlaceAdd)
1463 PYBIND11_MATH_OPERATOR_BINARY(operator-, PyNumber_Subtract)
1464 PYBIND11_MATH_OPERATOR_BINARY(operator-=, PyNumber_InPlaceSubtract)
1465 PYBIND11_MATH_OPERATOR_BINARY(operator*, PyNumber_Multiply)
1466 PYBIND11_MATH_OPERATOR_BINARY(operator*=, PyNumber_InPlaceMultiply)
1467 PYBIND11_MATH_OPERATOR_BINARY(operator/, PyNumber_TrueDivide)
1468 PYBIND11_MATH_OPERATOR_BINARY(operator/=, PyNumber_InPlaceTrueDivide)
1469 PYBIND11_MATH_OPERATOR_BINARY(operator|, PyNumber_Or)
1470 PYBIND11_MATH_OPERATOR_BINARY(operator|=, PyNumber_InPlaceOr)
1471 PYBIND11_MATH_OPERATOR_BINARY(operator&, PyNumber_And)
1472 PYBIND11_MATH_OPERATOR_BINARY(operator&=, PyNumber_InPlaceAnd)
1473 PYBIND11_MATH_OPERATOR_BINARY(operator^, PyNumber_Xor)
1474 PYBIND11_MATH_OPERATOR_BINARY(operator^=, PyNumber_InPlaceXor)
1475 PYBIND11_MATH_OPERATOR_BINARY(operator<<, PyNumber_Lshift)
1476 PYBIND11_MATH_OPERATOR_BINARY(operator<<=, PyNumber_InPlaceLshift)
1477 PYBIND11_MATH_OPERATOR_BINARY(operator>>, PyNumber_Rshift)
1478 PYBIND11_MATH_OPERATOR_BINARY(operator>>=, PyNumber_InPlaceRshift)
1480 #undef PYBIND11_MATH_OPERATOR_UNARY
1481 #undef PYBIND11_MATH_OPERATOR_BINARY
1483 NAMESPACE_END(detail)
1484 NAMESPACE_END(PYBIND11_NAMESPACE)