pytypes.h revision 12391:ceeca8b41e4b
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 17NAMESPACE_BEGIN(PYBIND11_NAMESPACE) 18 19/* A few forward declarations */ 20class handle; class object; 21class str; class iterator; 22struct arg; struct arg_v; 23 24NAMESPACE_BEGIN(detail) 25class args_proxy; 26inline bool isinstance_generic(handle obj, const std::type_info &tp); 27 28// Accessor forward declarations 29template <typename Policy> class accessor; 30namespace 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} 38using obj_attr_accessor = accessor<accessor_policies::obj_attr>; 39using str_attr_accessor = accessor<accessor_policies::str_attr>; 40using item_accessor = accessor<accessor_policies::generic_item>; 41using sequence_accessor = accessor<accessor_policies::sequence_item>; 42using list_accessor = accessor<accessor_policies::list_item>; 43using tuple_accessor = accessor<accessor_policies::tuple_item>; 44 45/// Tag and check to identify a class which implements the Python object API 46class pyobject_tag { }; 47template <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 */ 53template <typename Derived> 54class object_api : public pyobject_tag { 55 const Derived &derived() const { return static_cast<const Derived &>(*this); } 56 57public: 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. 114 bool is(object_api const& other) const { return derived().ptr() == other.derived().ptr(); } 115 /// Equivalent to ``obj is None`` in Python. 116 bool is_none() const { return derived().ptr() == Py_None; } 117 PYBIND11_DEPRECATED("Use py::str(obj) instead") 118 pybind11::str str() const; 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 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 129NAMESPACE_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 */ 142class handle : public detail::object_api<handle> { 143public: 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; } 184protected: 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 */ 198class object : public handle { 199public: 200 object() = default; 201 PYBIND11_DEPRECATED("Use reinterpret_borrow<object>() or reinterpret_steal<object>()") 202 object(handle h, bool is_borrowed) : handle(h) { if (is_borrowed) inc_ref(); } 203 /// Copy constructor; always increases the reference count 204 object(const object &o) : handle(o) { inc_ref(); } 205 /// Move constructor; steals the object from ``other`` and preserves its reference count 206 object(object &&other) noexcept { m_ptr = other.m_ptr; other.m_ptr = nullptr; } 207 /// Destructor; automatically calls `handle::dec_ref()` 208 ~object() { dec_ref(); } 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 */ 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 243protected: 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 251public: 252 // Only accessible from derived classes and the reinterpret_* functions 253 object(handle h, borrowed_t) : handle(h) { inc_ref(); } 254 object(handle h, stolen_t) : handle(h) { } 255}; 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 */ 270template <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 */ 280template <typename T> T reinterpret_steal(handle h) { return {h, object::stolen_t{}}; } 281 282NAMESPACE_BEGIN(detail) 283inline std::string error_string(); 284NAMESPACE_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). 290class error_already_set : public std::runtime_error { 291public: 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 314private: 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 */ 328template <typename T, detail::enable_if_t<std::is_base_of<object, T>::value, int> = 0> 329bool isinstance(handle obj) { return T::check_(obj); } 330 331template <typename T, detail::enable_if_t<!std::is_base_of<object, T>::value, int> = 0> 332bool isinstance(handle obj) { return detail::isinstance_generic(obj, typeid(T)); } 333 334template <> inline bool isinstance<handle>(handle obj) = delete; 335template <> 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``. 339inline 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/// @{ 348inline bool hasattr(handle obj, handle name) { 349 return PyObject_HasAttr(obj.ptr(), name.ptr()) == 1; 350} 351 352inline bool hasattr(handle obj, const char *name) { 353 return PyObject_HasAttrString(obj.ptr(), name) == 1; 354} 355 356inline 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 362inline 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 368inline 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 377inline 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 386inline 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 390inline 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 394inline 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 402NAMESPACE_BEGIN(detail) 403inline 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`. 419template <typename T, enable_if_t<is_pyobject<T>::value, int> = 0> 420auto 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: 422template <typename T, enable_if_t<!is_pyobject<T>::value, int> = 0> 423object object_or_cast(T &&o); 424// Match a PyObject*, which we want to convert directly to handle via its converting constructor 425inline handle object_or_cast(PyObject *ptr) { return ptr; } 426 427 428template <typename Policy> 429class accessor : public object_api<accessor<Policy>> { 430 using key_type = typename Policy::key_type; 431 432public: 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 461 operator object() const { return get_cache(); } 462 PyObject *ptr() const { return get_cache().ptr(); } 463 template <typename T> T cast() const { return get_cache().template cast<T>(); } 464 465private: 466 object &get_cache() const { 467 if (!cache) { cache = Policy::get(obj, key); } 468 return cache; 469 } 470 471private: 472 handle obj; 473 key_type key; 474 mutable object cache; 475}; 476 477NAMESPACE_BEGIN(accessor_policies) 478struct obj_attr { 479 using key_type = object; 480 static object get(handle obj, handle key) { return getattr(obj, key); } 481 static void set(handle obj, handle key, handle val) { setattr(obj, key, val); } 482}; 483 484struct str_attr { 485 using key_type = const char *; 486 static object get(handle obj, const char *key) { return getattr(obj, key); } 487 static void set(handle obj, const char *key, handle val) { setattr(obj, key, val); } 488}; 489 490struct generic_item { 491 using key_type = object; 492 493 static object get(handle obj, handle key) { 494 PyObject *result = PyObject_GetItem(obj.ptr(), key.ptr()); 495 if (!result) { throw error_already_set(); } 496 return reinterpret_steal<object>(result); 497 } 498 499 static void set(handle obj, handle key, handle val) { 500 if (PyObject_SetItem(obj.ptr(), key.ptr(), val.ptr()) != 0) { throw error_already_set(); } 501 } 502}; 503 504struct sequence_item { 505 using key_type = size_t; 506 507 static object get(handle obj, size_t index) { 508 PyObject *result = PySequence_GetItem(obj.ptr(), static_cast<ssize_t>(index)); 509 if (!result) { throw error_already_set(); } 510 return reinterpret_steal<object>(result); 511 } 512 513 static void set(handle obj, size_t index, handle val) { 514 // PySequence_SetItem does not steal a reference to 'val' 515 if (PySequence_SetItem(obj.ptr(), static_cast<ssize_t>(index), val.ptr()) != 0) { 516 throw error_already_set(); 517 } 518 } 519}; 520 521struct list_item { 522 using key_type = size_t; 523 524 static object get(handle obj, size_t index) { 525 PyObject *result = PyList_GetItem(obj.ptr(), static_cast<ssize_t>(index)); 526 if (!result) { throw error_already_set(); } 527 return reinterpret_borrow<object>(result); 528 } 529 530 static void set(handle obj, size_t index, handle val) { 531 // PyList_SetItem steals a reference to 'val' 532 if (PyList_SetItem(obj.ptr(), static_cast<ssize_t>(index), val.inc_ref().ptr()) != 0) { 533 throw error_already_set(); 534 } 535 } 536}; 537 538struct tuple_item { 539 using key_type = size_t; 540 541 static object get(handle obj, size_t index) { 542 PyObject *result = PyTuple_GetItem(obj.ptr(), static_cast<ssize_t>(index)); 543 if (!result) { throw error_already_set(); } 544 return reinterpret_borrow<object>(result); 545 } 546 547 static void set(handle obj, size_t index, handle val) { 548 // PyTuple_SetItem steals a reference to 'val' 549 if (PyTuple_SetItem(obj.ptr(), static_cast<ssize_t>(index), val.inc_ref().ptr()) != 0) { 550 throw error_already_set(); 551 } 552 } 553}; 554NAMESPACE_END(accessor_policies) 555 556/// STL iterator template used for tuple, list, sequence and dict 557template <typename Policy> 558class generic_iterator : public Policy { 559 using It = generic_iterator; 560 561public: 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 595NAMESPACE_BEGIN(iterator_policies) 596/// Quick proxy class needed to implement ``operator->`` for iterators which can't return pointers 597template <typename T> 598struct arrow_proxy { 599 T value; 600 601 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`` 606class sequence_fast_readonly { 607protected: 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 613 sequence_fast_readonly(handle obj, ssize_t n) : ptr(PySequence_Fast_ITEMS(obj.ptr()) + n) { } 614 615 reference dereference() const { return *ptr; } 616 void increment() { ++ptr; } 617 void decrement() { --ptr; } 618 void advance(ssize_t n) { ptr += n; } 619 bool equal(const sequence_fast_readonly &b) const { return ptr == b.ptr; } 620 ssize_t distance_to(const sequence_fast_readonly &b) const { return ptr - b.ptr; } 621 622private: 623 PyObject **ptr; 624}; 625 626/// Full read and write access using the sequence protocol: see ``detail::sequence_accessor`` 627class sequence_slow_readwrite { 628protected: 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 634 sequence_slow_readwrite(handle obj, ssize_t index) : obj(obj), index(index) { } 635 636 reference dereference() const { return {obj, static_cast<size_t>(index)}; } 637 void increment() { ++index; } 638 void decrement() { --index; } 639 void advance(ssize_t n) { index += n; } 640 bool equal(const sequence_slow_readwrite &b) const { return index == b.index; } 641 ssize_t distance_to(const sequence_slow_readwrite &b) const { return index - b.index; } 642 643private: 644 handle obj; 645 ssize_t index; 646}; 647 648/// Python's dictionary protocol permits this to be a forward iterator 649class dict_readonly { 650protected: 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; 657 dict_readonly(handle obj, ssize_t pos) : obj(obj), pos(pos) { increment(); } 658 659 reference dereference() const { return {key, value}; } 660 void increment() { if (!PyDict_Next(obj.ptr(), &pos, &key, &value)) { pos = -1; } } 661 bool equal(const dict_readonly &b) const { return pos == b.pos; } 662 663private: 664 handle obj; 665 PyObject *key, *value; 666 ssize_t pos = -1; 667}; 668NAMESPACE_END(iterator_policies) 669 670#if !defined(PYPY_VERSION) 671using tuple_iterator = generic_iterator<iterator_policies::sequence_fast_readonly>; 672using list_iterator = generic_iterator<iterator_policies::sequence_fast_readonly>; 673#else 674using tuple_iterator = generic_iterator<iterator_policies::sequence_slow_readwrite>; 675using list_iterator = generic_iterator<iterator_policies::sequence_slow_readwrite>; 676#endif 677 678using sequence_iterator = generic_iterator<iterator_policies::sequence_slow_readwrite>; 679using dict_iterator = generic_iterator<iterator_policies::dict_readonly>; 680 681inline 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 692inline bool PyNone_Check(PyObject *o) { return o == Py_None; } 693 694inline bool PyUnicode_Check_Permissive(PyObject *o) { return PyUnicode_Check(o) || PYBIND11_BYTES_CHECK(o); } 695 696class kwargs_proxy : public handle { 697public: 698 explicit kwargs_proxy(handle h) : handle(h) { } 699}; 700 701class args_proxy : public handle { 702public: 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) 708template <typename T> using is_keyword = std::is_base_of<arg, T>; 709template <typename T> using is_s_unpacking = std::is_same<args_proxy, T>; // * unpacking 710template <typename T> using is_ds_unpacking = std::is_same<kwargs_proxy, T>; // ** unpacking 711template <typename T> using is_positional = satisfies_none_of<T, 712 is_keyword, is_s_unpacking, is_ds_unpacking 713>; 714template <typename T> using is_keyword_or_ds = satisfies_any_of<T, is_keyword, is_ds_unpacking>; 715 716// Call argument collector forward declarations 717template <return_value_policy policy = return_value_policy::automatic_reference> 718class simple_collector; 719template <return_value_policy policy = return_value_policy::automatic_reference> 720class unpacking_collector; 721 722NAMESPACE_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 */ 771class iterator : public object { 772public: 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 820private: 821 void advance() { 822 value = reinterpret_steal<object>(PyIter_Next(m_ptr)); 823 if (PyErr_Occurred()) { throw error_already_set(); } 824 } 825 826private: 827 object value = {}; 828}; 829 830class iterable : public object { 831public: 832 PYBIND11_OBJECT_DEFAULT(iterable, object, detail::PyIterable_Check) 833}; 834 835class bytes; 836 837class str : public object { 838public: 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 = "") 848 : object(PyUnicode_FromString(c), stolen_t{}) { 849 if (!m_ptr) pybind11_fail("Could not allocate string object!"); 850 } 851 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 */ 860 explicit str(handle h) : object(raw_str(h.ptr()), stolen_t{}) { } 861 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> 877 str format(Args &&...args) const { 878 return attr("format")(std::forward<Args>(args)...); 879 } 880 881private: 882 /// Return string representation -- always returns a new reference, even if already a str 883 static PyObject *raw_str(PyObject *op) { 884 PyObject *str_value = PyObject_Str(op); 885#if PY_MAJOR_VERSION < 3 886 if (!str_value) throw error_already_set(); 887 PyObject *unicode = PyUnicode_FromEncodedObject(str_value, "utf-8", nullptr); 888 Py_XDECREF(str_value); str_value = unicode; 889#endif 890 return str_value; 891 } 892}; 893/// @} pytypes 894 895inline namespace literals { 896/** \rst 897 String literal version of `str` 898 \endrst */ 899inline str operator"" _s(const char *s, size_t size) { return {s, size}; } 900} 901 902/// \addtogroup pytypes 903/// @{ 904class bytes : public object { 905public: 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 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: 920 bytes(const std::string &s) : bytes(s.data(), s.size()) { } 921 922 explicit bytes(const pybind11::str &s); 923 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 933inline 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 950inline 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 961class none : public object { 962public: 963 PYBIND11_OBJECT(none, object, detail::PyNone_Check) 964 none() : object(Py_None, borrowed_t{}) { } 965}; 966 967class bool_ : public object { 968public: 969 PYBIND11_OBJECT_CVT(bool_, object, PyBool_Check, raw_bool) 970 bool_() : object(Py_False, borrowed_t{}) { } 971 // Allow implicit conversion from and to `bool`: 972 bool_(bool value) : object(value ? Py_True : Py_False, borrowed_t{}) { } 973 operator bool() const { return m_ptr && PyLong_AsLong(m_ptr) != 0; } 974 975private: 976 /// Return the truth value of an object -- always returns a new reference 977 static PyObject *raw_bool(PyObject *op) { 978 const auto value = PyObject_IsTrue(op); 979 if (value == -1) return nullptr; 980 return handle(value ? Py_True : Py_False).inc_ref().ptr(); 981 } 982}; 983 984NAMESPACE_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). 989template <typename Unsigned> 990Unsigned 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} 1004NAMESPACE_END(detail) 1005 1006class int_ : public object { 1007public: 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 1039class float_ : public object { 1040public: 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 1053class weakref : public object { 1054public: 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 1062class slice : public object { 1063public: 1064 PYBIND11_OBJECT_DEFAULT(slice, object, PySlice_Check) 1065 slice(ssize_t start_, ssize_t stop_, ssize_t step_) { 1066 int_ start(start_), stop(stop_), step(step_); 1067 m_ptr = PySlice_New(start.ptr(), stop.ptr(), step.ptr()); 1068 if (!m_ptr) pybind11_fail("Could not allocate slice object!"); 1069 } 1070 bool compute(size_t length, size_t *start, size_t *stop, size_t *step, 1071 size_t *slicelength) const { 1072 return PySlice_GetIndicesEx((PYBIND11_SLICE_OBJECT *) m_ptr, 1073 (ssize_t) length, (ssize_t *) start, 1074 (ssize_t *) stop, (ssize_t *) step, 1075 (ssize_t *) slicelength) == 0; 1076 } 1077}; 1078 1079class capsule : public object { 1080public: 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) 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") 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 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 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 1129 const char *name() const { return PyCapsule_GetName(m_ptr); } 1130}; 1131 1132class tuple : public object { 1133public: 1134 PYBIND11_OBJECT_CVT(tuple, object, PyTuple_Check, PySequence_Tuple) 1135 explicit tuple(size_t size = 0) : object(PyTuple_New((ssize_t) size), stolen_t{}) { 1136 if (!m_ptr) pybind11_fail("Could not allocate tuple object!"); 1137 } 1138 size_t size() const { return (size_t) PyTuple_Size(m_ptr); } 1139 detail::tuple_accessor operator[](size_t index) const { return {*this, index}; } 1140 detail::tuple_iterator begin() const { return {*this, 0}; } 1141 detail::tuple_iterator end() const { return {*this, PyTuple_GET_SIZE(m_ptr)}; } 1142}; 1143 1144class dict : public object { 1145public: 1146 PYBIND11_OBJECT_CVT(dict, object, PyDict_Check, raw_dict) 1147 dict() : object(PyDict_New(), stolen_t{}) { 1148 if (!m_ptr) pybind11_fail("Could not allocate dict object!"); 1149 } 1150 template <typename... Args, 1151 typename = detail::enable_if_t<detail::all_of<detail::is_keyword_or_ds<Args>...>::value>, 1152 // MSVC workaround: it can't compile an out-of-line definition, so defer the collector 1153 typename collector = detail::deferred_t<detail::unpacking_collector<>, Args...>> 1154 explicit dict(Args &&...args) : dict(collector(std::forward<Args>(args)...).kwargs()) { } 1155 1156 size_t size() const { return (size_t) PyDict_Size(m_ptr); } 1157 detail::dict_iterator begin() const { return {*this, 0}; } 1158 detail::dict_iterator end() const { return {}; } 1159 void clear() const { PyDict_Clear(ptr()); } 1160 bool contains(handle key) const { return PyDict_Contains(ptr(), key.ptr()) == 1; } 1161 bool contains(const char *key) const { return PyDict_Contains(ptr(), pybind11::str(key).ptr()) == 1; } 1162 1163private: 1164 /// Call the `dict` Python type -- always returns a new reference 1165 static PyObject *raw_dict(PyObject *op) { 1166 if (PyDict_Check(op)) 1167 return handle(op).inc_ref().ptr(); 1168 return PyObject_CallFunctionObjArgs((PyObject *) &PyDict_Type, op, nullptr); 1169 } 1170}; 1171 1172class sequence : public object { 1173public: 1174 PYBIND11_OBJECT_DEFAULT(sequence, object, PySequence_Check) 1175 size_t size() const { return (size_t) PySequence_Size(m_ptr); } 1176 detail::sequence_accessor operator[](size_t index) const { return {*this, index}; } 1177 detail::sequence_iterator begin() const { return {*this, 0}; } 1178 detail::sequence_iterator end() const { return {*this, PySequence_Size(m_ptr)}; } 1179}; 1180 1181class list : public object { 1182public: 1183 PYBIND11_OBJECT_CVT(list, object, PyList_Check, PySequence_List) 1184 explicit list(size_t size = 0) : object(PyList_New((ssize_t) size), stolen_t{}) { 1185 if (!m_ptr) pybind11_fail("Could not allocate list object!"); 1186 } 1187 size_t size() const { return (size_t) PyList_Size(m_ptr); } 1188 detail::list_accessor operator[](size_t index) const { return {*this, index}; } 1189 detail::list_iterator begin() const { return {*this, 0}; } 1190 detail::list_iterator end() const { return {*this, PyList_GET_SIZE(m_ptr)}; } 1191 template <typename T> void append(T &&val) const { 1192 PyList_Append(m_ptr, detail::object_or_cast(std::forward<T>(val)).ptr()); 1193 } 1194}; 1195 1196class args : public tuple { PYBIND11_OBJECT_DEFAULT(args, tuple, PyTuple_Check) }; 1197class kwargs : public dict { PYBIND11_OBJECT_DEFAULT(kwargs, dict, PyDict_Check) }; 1198 1199class set : public object { 1200public: 1201 PYBIND11_OBJECT_CVT(set, object, PySet_Check, PySet_New) 1202 set() : object(PySet_New(nullptr), stolen_t{}) { 1203 if (!m_ptr) pybind11_fail("Could not allocate set object!"); 1204 } 1205 size_t size() const { return (size_t) PySet_Size(m_ptr); } 1206 template <typename T> bool add(T &&val) const { 1207 return PySet_Add(m_ptr, detail::object_or_cast(std::forward<T>(val)).ptr()) == 0; 1208 } 1209 void clear() const { PySet_Clear(m_ptr); } 1210}; 1211 1212class function : public object { 1213public: 1214 PYBIND11_OBJECT_DEFAULT(function, object, PyCallable_Check) 1215 handle cpp_function() const { 1216 handle fun = detail::get_function(m_ptr); 1217 if (fun && PyCFunction_Check(fun.ptr())) 1218 return fun; 1219 return handle(); 1220 } 1221 bool is_cpp_function() const { return (bool) cpp_function(); } 1222}; 1223 1224class buffer : public object { 1225public: 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 1240class memoryview : public object { 1241public: 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/// @{ 1275inline 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 1282inline 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 1293inline 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 1300NAMESPACE_BEGIN(detail) 1301template <typename D> iterator object_api<D>::begin() const { return iter(derived()); } 1302template <typename D> iterator object_api<D>::end() const { return iterator::sentinel(); } 1303template <typename D> item_accessor object_api<D>::operator[](handle key) const { 1304 return {derived(), reinterpret_borrow<object>(key)}; 1305} 1306template <typename D> item_accessor object_api<D>::operator[](const char *key) const { 1307 return {derived(), pybind11::str(key)}; 1308} 1309template <typename D> obj_attr_accessor object_api<D>::attr(handle key) const { 1310 return {derived(), reinterpret_borrow<object>(key)}; 1311} 1312template <typename D> str_attr_accessor object_api<D>::attr(const char *key) const { 1313 return {derived(), key}; 1314} 1315template <typename D> args_proxy object_api<D>::operator*() const { 1316 return args_proxy(derived().ptr()); 1317} 1318template <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 1322template <typename D> 1323pybind11::str object_api<D>::str() const { return pybind11::str(derived()); } 1324 1325template <typename D> 1326str_attr_accessor object_api<D>::doc() const { return attr("__doc__"); } 1327 1328template <typename D> 1329handle object_api<D>::get_type() const { return (PyObject *) Py_TYPE(derived().ptr()); } 1330 1331NAMESPACE_END(detail) 1332NAMESPACE_END(PYBIND11_NAMESPACE) 1333