python_packaging/src/external/pybind/include/pybind11/pytypes.h

   1 /*
   2     pybind11/pytypes.h: Convenience wrapper classes for basic Python types
   3
   4     Copyright (c) 2016 Wenzel Jakob <wenzel.jakob@epfl.ch>
   5
   6     All rights reserved. Use of this source code is governed by a
   7     BSD-style license that can be found in the LICENSE file.
   8 */
   9
  10 #pragma once
  11
  12 #include "detail/common.h"
  13 #include "buffer_info.h"
  14 #include <utility>
  15 #include <type_traits>
  16
  17 NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
  18
  19 /* A few forward declarations */
  20 class handle; class object;
  21 class str; class iterator;
  22 struct arg; struct arg_v;
  23
  24 NAMESPACE_BEGIN(detail)
  25 class args_proxy;
  26 inline bool isinstance_generic(handle obj, const std::type_info &tp);
  27
  28 // Accessor forward declarations
  29 template <typename Policy> class accessor;
  30 namespace accessor_policies {
  31     struct obj_attr;
  32     struct str_attr;
  33     struct generic_item;
  34     struct sequence_item;
  35     struct list_item;
  36     struct tuple_item;
  37 }
  38 using obj_attr_accessor = accessor<accessor_policies::obj_attr>;
  39 using str_attr_accessor = accessor<accessor_policies::str_attr>;
  40 using item_accessor = accessor<accessor_policies::generic_item>;
  41 using sequence_accessor = accessor<accessor_policies::sequence_item>;
  42 using list_accessor = accessor<accessor_policies::list_item>;
  43 using tuple_accessor = accessor<accessor_policies::tuple_item>;
  44
  45 /// Tag and check to identify a class which implements the Python object API
  46 class pyobject_tag { };
  47 template <typename T> using is_pyobject = std::is_base_of<pyobject_tag, remove_reference_t<T>>;
  48
  49 /** \rst
  50     A mixin class which adds common functions to `handle`, `object` and various accessors.
  51     The only requirement for `Derived` is to implement ``PyObject *Derived::ptr() const``.
  52 \endrst */
  53 template <typename Derived>
  54 class object_api : public pyobject_tag {
  55     const Derived &derived() const { return static_cast<const Derived &>(*this); }
  56
  57 public:
  58     /** \rst
  59         Return an iterator equivalent to calling ``iter()`` in Python. The object
  60         must be a collection which supports the iteration protocol.
  61     \endrst */
  62     iterator begin() const;
  63     /// Return a sentinel which ends iteration.
  64     iterator end() const;
  65
  66     /** \rst
  67         Return an internal functor to invoke the object's sequence protocol. Casting
  68         the returned ``detail::item_accessor`` instance to a `handle` or `object`
  69         subclass causes a corresponding call to ``__getitem__``. Assigning a `handle`
  70         or `object` subclass causes a call to ``__setitem__``.
  71     \endrst */
  72     item_accessor operator[](handle key) const;
  73     /// See above (the only difference is that they key is provided as a string literal)
  74     item_accessor operator[](const char *key) const;
  75
  76     /** \rst
  77         Return an internal functor to access the object's attributes. Casting the
  78         returned ``detail::obj_attr_accessor`` instance to a `handle` or `object`
  79         subclass causes a corresponding call to ``getattr``. Assigning a `handle`
  80         or `object` subclass causes a call to ``setattr``.
  81     \endrst */
  82     obj_attr_accessor attr(handle key) const;
  83     /// See above (the only difference is that they key is provided as a string literal)
  84     str_attr_accessor attr(const char *key) const;
  85
  86     /** \rst
  87         Matches * unpacking in Python, e.g. to unpack arguments out of a ``tuple``
  88         or ``list`` for a function call. Applying another * to the result yields
  89         ** unpacking, e.g. to unpack a dict as function keyword arguments.
  90         See :ref:`calling_python_functions`.
  91     \endrst */
  92     args_proxy operator*() const;
  93
  94     /// Check if the given item is contained within this object, i.e. ``item in obj``.
  95     template <typename T> bool contains(T &&item) const;
  96
  97     /** \rst
  98         Assuming the Python object is a function or implements the ``__call__``
  99         protocol, ``operator()`` invokes the underlying function, passing an
 100         arbitrary set of parameters. The result is returned as a `object` and
 101         may need to be converted back into a Python object using `handle::cast()`.
 102
 103         When some of the arguments cannot be converted to Python objects, the
 104         function will throw a `cast_error` exception. When the Python function
 105         call fails, a `error_already_set` exception is thrown.
 106     \endrst */
 107     template <return_value_policy policy = return_value_policy::automatic_reference, typename... Args>
 108     object operator()(Args &&...args) const;
 109     template <return_value_policy policy = return_value_policy::automatic_reference, typename... Args>
 110     PYBIND11_DEPRECATED("call(...) was deprecated in favor of operator()(...)")
 111         object call(Args&&... args) const;
 112
 113     /// Equivalent to ``obj is other`` in Python.
 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
 129 NAMESPACE_END(detail)
 130
 131 /** \rst
 132     Holds a reference to a Python object (no reference counting)
 133
 134     The `handle` class is a thin wrapper around an arbitrary Python object (i.e. a
 135     ``PyObject *`` in Python's C API). It does not perform any automatic reference
 136     counting and merely provides a basic C++ interface to various Python API functions.
 137
 138     .. seealso::
 139         The `object` class inherits from `handle` and adds automatic reference
 140         counting features.
 141 \endrst */
 142 class handle : public detail::object_api<handle> {
 143 public:
 144     /// The default constructor creates a handle with a ``nullptr``-valued pointer
 145     handle() = default;
 146     /// Creates a ``handle`` from the given raw Python object pointer
 147     handle(PyObject *ptr) : m_ptr(ptr) { } // Allow implicit conversion from PyObject*
 148
 149     /// Return the underlying ``PyObject *`` pointer
 150     PyObject *ptr() const { return m_ptr; }
 151     PyObject *&ptr() { return m_ptr; }
 152
 153     /** \rst
 154         Manually increase the reference count of the Python object. Usually, it is
 155         preferable to use the `object` class which derives from `handle` and calls
 156         this function automatically. Returns a reference to itself.
 157     \endrst */
 158     const handle& inc_ref() const & { Py_XINCREF(m_ptr); return *this; }
 159
 160     /** \rst
 161         Manually decrease the reference count of the Python object. Usually, it is
 162         preferable to use the `object` class which derives from `handle` and calls
 163         this function automatically. Returns a reference to itself.
 164     \endrst */
 165     const handle& dec_ref() const & { Py_XDECREF(m_ptr); return *this; }
 166
 167     /** \rst
 168         Attempt to cast the Python object into the given C++ type. A `cast_error`
 169         will be throw upon failure.
 170     \endrst */
 171     template <typename T> T cast() const;
 172     /// Return ``true`` when the `handle` wraps a valid Python object
 173     explicit operator bool() const { return m_ptr != nullptr; }
 174     /** \rst
 175         Deprecated: Check that the underlying pointers are the same.
 176         Equivalent to ``obj1 is obj2`` in Python.
 177     \endrst */
 178     PYBIND11_DEPRECATED("Use obj1.is(obj2) instead")
 179     bool operator==(const handle &h) const { return m_ptr == h.m_ptr; }
 180     PYBIND11_DEPRECATED("Use !obj1.is(obj2) instead")
 181     bool operator!=(const handle &h) const { return m_ptr != h.m_ptr; }
 182     PYBIND11_DEPRECATED("Use handle::operator bool() instead")
 183     bool check() const { return m_ptr != nullptr; }
 184 protected:
 185     PyObject *m_ptr = nullptr;
 186 };
 187
 188 /** \rst
 189     Holds a reference to a Python object (with reference counting)
 190
 191     Like `handle`, the `object` class is a thin wrapper around an arbitrary Python
 192     object (i.e. a ``PyObject *`` in Python's C API). In contrast to `handle`, it
 193     optionally increases the object's reference count upon construction, and it
 194     *always* decreases the reference count when the `object` instance goes out of
 195     scope and is destructed. When using `object` instances consistently, it is much
 196     easier to get reference counting right at the first attempt.
 197 \endrst */
 198 class object : public handle {
 199 public:
 200     object() = default;
 201     PYBIND11_DEPRECATED("Use reinterpret_borrow<object>() or reinterpret_steal<object>()")
 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
 243 protected:
 244     // Tags for choosing constructors from raw PyObject *
 245     struct borrowed_t { };
 246     struct stolen_t { };
 247
 248     template <typename T> friend T reinterpret_borrow(handle);
 249     template <typename T> friend T reinterpret_steal(handle);
 250
 251 public:
 252     // Only accessible from derived classes and the reinterpret_* functions
 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 */
 270 template <typename T> T reinterpret_borrow(handle h) { return {h, object::borrowed_t{}}; }
 271
 272 /** \rst
 273     Like `reinterpret_borrow`, but steals the reference.
 274
 275      .. code-block:: cpp
 276
 277         PyObject *p = PyObject_Str(obj);
 278         py::str s = reinterpret_steal<py::str>(p); // <-- `p` must be already be a `str`
 279 \endrst */
 280 template <typename T> T reinterpret_steal(handle h) { return {h, object::stolen_t{}}; }
 281
 282 NAMESPACE_BEGIN(detail)
 283 inline std::string error_string();
 284 NAMESPACE_END(detail)
 285
 286 /// Fetch and hold an error which was already set in Python.  An instance of this is typically
 287 /// thrown to propagate python-side errors back through C++ which can either be caught manually or
 288 /// else falls back to the function dispatcher (which then raises the captured error back to
 289 /// python).
 290 class error_already_set : public std::runtime_error {
 291 public:
 292     /// Constructs a new exception from the current Python error indicator, if any.  The current
 293     /// Python error indicator will be cleared.
 294     error_already_set() : std::runtime_error(detail::error_string()) {
 295         PyErr_Fetch(&type.ptr(), &value.ptr(), &trace.ptr());
 296     }
 297
 298     inline ~error_already_set();
 299
 300     /// Give the currently-held error back to Python, if any.  If there is currently a Python error
 301     /// already set it is cleared first.  After this call, the current object no longer stores the
 302     /// error variables (but the `.what()` string is still available).
 303     void restore() { PyErr_Restore(type.release().ptr(), value.release().ptr(), trace.release().ptr()); }
 304
 305     // Does nothing; provided for backwards compatibility.
 306     PYBIND11_DEPRECATED("Use of error_already_set.clear() is deprecated")
 307     void clear() {}
 308
 309     /// Check if the currently trapped error type matches the given Python exception class (or a
 310     /// subclass thereof).  May also be passed a tuple to search for any exception class matches in
 311     /// the given tuple.
 312     bool matches(handle ex) const { return PyErr_GivenExceptionMatches(ex.ptr(), type.ptr()); }
 313
 314 private:
 315     object type, value, trace;
 316 };
 317
 318 /** \defgroup python_builtins _
 319     Unless stated otherwise, the following C++ functions behave the same
 320     as their Python counterparts.
 321  */
 322
 323 /** \ingroup python_builtins
 324     \rst
 325     Return true if ``obj`` is an instance of ``T``. Type ``T`` must be a subclass of
 326     `object` or a class which was exposed to Python as ``py::class_<T>``.
 327 \endrst */
 328 template <typename T, detail::enable_if_t<std::is_base_of<object, T>::value, int> = 0>
 329 bool isinstance(handle obj) { return T::check_(obj); }
 330
 331 template <typename T, detail::enable_if_t<!std::is_base_of<object, T>::value, int> = 0>
 332 bool isinstance(handle obj) { return detail::isinstance_generic(obj, typeid(T)); }
 333
 334 template <> inline bool isinstance<handle>(handle obj) = delete;
 335 template <> inline bool isinstance<object>(handle obj) { return obj.ptr() != nullptr; }
 336
 337 /// \ingroup python_builtins
 338 /// Return true if ``obj`` is an instance of the ``type``.
 339 inline bool isinstance(handle obj, handle type) {
 340     const auto result = PyObject_IsInstance(obj.ptr(), type.ptr());
 341     if (result == -1)
 342         throw error_already_set();
 343     return result != 0;
 344 }
 345
 346 /// \addtogroup python_builtins
 347 /// @{
 348 inline bool hasattr(handle obj, handle name) {
 349     return PyObject_HasAttr(obj.ptr(), name.ptr()) == 1;
 350 }
 351
 352 inline bool hasattr(handle obj, const char *name) {
 353     return PyObject_HasAttrString(obj.ptr(), name) == 1;
 354 }
 355
 356 inline object getattr(handle obj, handle name) {
 357     PyObject *result = PyObject_GetAttr(obj.ptr(), name.ptr());
 358     if (!result) { throw error_already_set(); }
 359     return reinterpret_steal<object>(result);
 360 }
 361
 362 inline object getattr(handle obj, const char *name) {
 363     PyObject *result = PyObject_GetAttrString(obj.ptr(), name);
 364     if (!result) { throw error_already_set(); }
 365     return reinterpret_steal<object>(result);
 366 }
 367
 368 inline object getattr(handle obj, handle name, handle default_) {
 369     if (PyObject *result = PyObject_GetAttr(obj.ptr(), name.ptr())) {
 370         return reinterpret_steal<object>(result);
 371     } else {
 372         PyErr_Clear();
 373         return reinterpret_borrow<object>(default_);
 374     }
 375 }
 376
 377 inline object getattr(handle obj, const char *name, handle default_) {
 378     if (PyObject *result = PyObject_GetAttrString(obj.ptr(), name)) {
 379         return reinterpret_steal<object>(result);
 380     } else {
 381         PyErr_Clear();
 382         return reinterpret_borrow<object>(default_);
 383     }
 384 }
 385
 386 inline void setattr(handle obj, handle name, handle value) {
 387     if (PyObject_SetAttr(obj.ptr(), name.ptr(), value.ptr()) != 0) { throw error_already_set(); }
 388 }
 389
 390 inline void setattr(handle obj, const char *name, handle value) {
 391     if (PyObject_SetAttrString(obj.ptr(), name, value.ptr()) != 0) { throw error_already_set(); }
 392 }
 393
 394 inline ssize_t hash(handle obj) {
 395     auto h = PyObject_Hash(obj.ptr());
 396     if (h == -1) { throw error_already_set(); }
 397     return h;
 398 }
 399
 400 /// @} python_builtins
 401
 402 NAMESPACE_BEGIN(detail)
 403 inline handle get_function(handle value) {
 404     if (value) {
 405 #if PY_MAJOR_VERSION >= 3
 406         if (PyInstanceMethod_Check(value.ptr()))
 407             value = PyInstanceMethod_GET_FUNCTION(value.ptr());
 408         else
 409 #endif
 410         if (PyMethod_Check(value.ptr()))
 411             value = PyMethod_GET_FUNCTION(value.ptr());
 412     }
 413     return value;
 414 }
 415
 416 // Helper aliases/functions to support implicit casting of values given to python accessors/methods.
 417 // When given a pyobject, this simply returns the pyobject as-is; for other C++ type, the value goes
 418 // through pybind11::cast(obj) to convert it to an `object`.
 419 template <typename T, enable_if_t<is_pyobject<T>::value, int> = 0>
 420 auto object_or_cast(T &&o) -> decltype(std::forward<T>(o)) { return std::forward<T>(o); }
 421 // The following casting version is implemented in cast.h:
 422 template <typename T, enable_if_t<!is_pyobject<T>::value, int> = 0>
 423 object object_or_cast(T &&o);
 424 // Match a PyObject*, which we want to convert directly to handle via its converting constructor
 425 inline handle object_or_cast(PyObject *ptr) { return ptr; }
 426
 427
 428 template <typename Policy>
 429 class accessor : public object_api<accessor<Policy>> {
 430     using key_type = typename Policy::key_type;
 431
 432 public:
 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
 465 private:
 466     object &get_cache() const {
 467         if (!cache) { cache = Policy::get(obj, key); }
 468         return cache;
 469     }
 470
 471 private:
 472     handle obj;
 473     key_type key;
 474     mutable object cache;
 475 };
 476
 477 NAMESPACE_BEGIN(accessor_policies)
 478 struct obj_attr {
 479     using key_type = object;
 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
 484 struct str_attr {
 485     using key_type = const char *;
 486     static object get(handle obj, const char *key) { return getattr(obj, key); }
 487     static void set(handle obj, const char *key, handle val) { setattr(obj, key, val); }
 488 };
 489
 490 struct 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
 504 struct 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
 521 struct 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
 538 struct 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 };
 554 NAMESPACE_END(accessor_policies)
 555
 556 /// STL iterator template used for tuple, list, sequence and dict
 557 template <typename Policy>
 558 class generic_iterator : public Policy {
 559     using It = generic_iterator;
 560
 561 public:
 562     using difference_type = ssize_t;
 563     using iterator_category = typename Policy::iterator_category;
 564     using value_type = typename Policy::value_type;
 565     using reference = typename Policy::reference;
 566     using pointer = typename Policy::pointer;
 567
 568     generic_iterator() = default;
 569     generic_iterator(handle seq, ssize_t index) : Policy(seq, index) { }
 570
 571     reference operator*() const { return Policy::dereference(); }
 572     reference operator[](difference_type n) const { return *(*this + n); }
 573     pointer operator->() const { return **this; }
 574
 575     It &operator++() { Policy::increment(); return *this; }
 576     It operator++(int) { auto copy = *this; Policy::increment(); return copy; }
 577     It &operator--() { Policy::decrement(); return *this; }
 578     It operator--(int) { auto copy = *this; Policy::decrement(); return copy; }
 579     It &operator+=(difference_type n) { Policy::advance(n); return *this; }
 580     It &operator-=(difference_type n) { Policy::advance(-n); return *this; }
 581
 582     friend It operator+(const It &a, difference_type n) { auto copy = a; return copy += n; }
 583     friend It operator+(difference_type n, const It &b) { return b + n; }
 584     friend It operator-(const It &a, difference_type n) { auto copy = a; return copy -= n; }
 585     friend difference_type operator-(const It &a, const It &b) { return a.distance_to(b); }
 586
 587     friend bool operator==(const It &a, const It &b) { return a.equal(b); }
 588     friend bool operator!=(const It &a, const It &b) { return !(a == b); }
 589     friend bool operator< (const It &a, const It &b) { return b - a > 0; }
 590     friend bool operator> (const It &a, const It &b) { return b < a; }
 591     friend bool operator>=(const It &a, const It &b) { return !(a < b); }
 592     friend bool operator<=(const It &a, const It &b) { return !(a > b); }
 593 };
 594
 595 NAMESPACE_BEGIN(iterator_policies)
 596 /// Quick proxy class needed to implement ``operator->`` for iterators which can't return pointers
 597 template <typename T>
 598 struct arrow_proxy {
 599     T value;
 600
 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``
 606 class sequence_fast_readonly {
 607 protected:
 608     using iterator_category = std::random_access_iterator_tag;
 609     using value_type = handle;
 610     using reference = const handle;
 611     using pointer = arrow_proxy<const handle>;
 612
 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
 622 private:
 623     PyObject **ptr;
 624 };
 625
 626 /// Full read and write access using the sequence protocol: see ``detail::sequence_accessor``
 627 class sequence_slow_readwrite {
 628 protected:
 629     using iterator_category = std::random_access_iterator_tag;
 630     using value_type = object;
 631     using reference = sequence_accessor;
 632     using pointer = arrow_proxy<const sequence_accessor>;
 633
 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
 643 private:
 644     handle obj;
 645     ssize_t index;
 646 };
 647
 648 /// Python's dictionary protocol permits this to be a forward iterator
 649 class dict_readonly {
 650 protected:
 651     using iterator_category = std::forward_iterator_tag;
 652     using value_type = std::pair<handle, handle>;
 653     using reference = const value_type;
 654     using pointer = arrow_proxy<const value_type>;
 655
 656     dict_readonly() = default;
 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
 663 private:
 664     handle obj;
 665     PyObject *key, *value;
 666     ssize_t pos = -1;
 667 };
 668 NAMESPACE_END(iterator_policies)
 669
 670 #if !defined(PYPY_VERSION)
 671 using tuple_iterator = generic_iterator<iterator_policies::sequence_fast_readonly>;
 672 using list_iterator = generic_iterator<iterator_policies::sequence_fast_readonly>;
 673 #else
 674 using tuple_iterator = generic_iterator<iterator_policies::sequence_slow_readwrite>;
 675 using list_iterator = generic_iterator<iterator_policies::sequence_slow_readwrite>;
 676 #endif
 677
 678 using sequence_iterator = generic_iterator<iterator_policies::sequence_slow_readwrite>;
 679 using dict_iterator = generic_iterator<iterator_policies::dict_readonly>;
 680
 681 inline bool PyIterable_Check(PyObject *obj) {
 682     PyObject *iter = PyObject_GetIter(obj);
 683     if (iter) {
 684         Py_DECREF(iter);
 685         return true;
 686     } else {
 687         PyErr_Clear();
 688         return false;
 689     }
 690 }
 691
 692 inline bool PyNone_Check(PyObject *o) { return o == Py_None; }
 693
 694 inline bool PyUnicode_Check_Permissive(PyObject *o) { return PyUnicode_Check(o) || PYBIND11_BYTES_CHECK(o); }
 695
 696 class kwargs_proxy : public handle {
 697 public:
 698     explicit kwargs_proxy(handle h) : handle(h) { }
 699 };
 700
 701 class args_proxy : public handle {
 702 public:
 703     explicit args_proxy(handle h) : handle(h) { }
 704     kwargs_proxy operator*() const { return kwargs_proxy(*this); }
 705 };
 706
 707 /// Python argument categories (using PEP 448 terms)
 708 template <typename T> using is_keyword = std::is_base_of<arg, T>;
 709 template <typename T> using is_s_unpacking = std::is_same<args_proxy, T>; // * unpacking
 710 template <typename T> using is_ds_unpacking = std::is_same<kwargs_proxy, T>; // ** unpacking
 711 template <typename T> using is_positional = satisfies_none_of<T,
 712     is_keyword, is_s_unpacking, is_ds_unpacking
 713 >;
 714 template <typename T> using is_keyword_or_ds = satisfies_any_of<T, is_keyword, is_ds_unpacking>;
 715
 716 // Call argument collector forward declarations
 717 template <return_value_policy policy = return_value_policy::automatic_reference>
 718 class simple_collector;
 719 template <return_value_policy policy = return_value_policy::automatic_reference>
 720 class unpacking_collector;
 721
 722 NAMESPACE_END(detail)
 723
 724 // TODO: After the deprecated constructors are removed, this macro can be simplified by
 725 //       inheriting ctors: `using Parent::Parent`. It's not an option right now because
 726 //       the `using` statement triggers the parent deprecation warning even if the ctor
 727 //       isn't even used.
 728 #define PYBIND11_OBJECT_COMMON(Name, Parent, CheckFun) \
 729     public: \
 730         PYBIND11_DEPRECATED("Use reinterpret_borrow<"#Name">() or reinterpret_steal<"#Name">()") \
 731         Name(handle h, bool is_borrowed) : Parent(is_borrowed ? Parent(h, borrowed_t{}) : Parent(h, stolen_t{})) { } \
 732         Name(handle h, borrowed_t) : Parent(h, borrowed_t{}) { } \
 733         Name(handle h, stolen_t) : Parent(h, stolen_t{}) { } \
 734         PYBIND11_DEPRECATED("Use py::isinstance<py::python_type>(obj) instead") \
 735         bool check() const { return m_ptr != nullptr && (bool) CheckFun(m_ptr); } \
 736         static bool check_(handle h) { return h.ptr() != nullptr && CheckFun(h.ptr()); }
 737
 738 #define PYBIND11_OBJECT_CVT(Name, Parent, CheckFun, ConvertFun) \
 739     PYBIND11_OBJECT_COMMON(Name, Parent, CheckFun) \
 740     /* This is deliberately not 'explicit' to allow implicit conversion from object: */ \
 741     Name(const object &o) \
 742     : Parent(check_(o) ? o.inc_ref().ptr() : ConvertFun(o.ptr()), stolen_t{}) \
 743     { if (!m_ptr) throw error_already_set(); } \
 744     Name(object &&o) \
 745     : Parent(check_(o) ? o.release().ptr() : ConvertFun(o.ptr()), stolen_t{}) \
 746     { if (!m_ptr) throw error_already_set(); } \
 747     template <typename Policy_> \
 748     Name(const ::pybind11::detail::accessor<Policy_> &a) : Name(object(a)) { }
 749
 750 #define PYBIND11_OBJECT(Name, Parent, CheckFun) \
 751     PYBIND11_OBJECT_COMMON(Name, Parent, CheckFun) \
 752     /* This is deliberately not 'explicit' to allow implicit conversion from object: */ \
 753     Name(const object &o) : Parent(o) { } \
 754     Name(object &&o) : Parent(std::move(o)) { }
 755
 756 #define PYBIND11_OBJECT_DEFAULT(Name, Parent, CheckFun) \
 757     PYBIND11_OBJECT(Name, Parent, CheckFun) \
 758     Name() : Parent() { }
 759
 760 /// \addtogroup pytypes
 761 /// @{
 762
 763 /** \rst
 764     Wraps a Python iterator so that it can also be used as a C++ input iterator
 765
 766     Caveat: copying an iterator does not (and cannot) clone the internal
 767     state of the Python iterable. This also applies to the post-increment
 768     operator. This iterator should only be used to retrieve the current
 769     value using ``operator*()``.
 770 \endrst */
 771 class iterator : public object {
 772 public:
 773     using iterator_category = std::input_iterator_tag;
 774     using difference_type = ssize_t;
 775     using value_type = handle;
 776     using reference = const handle;
 777     using pointer = const handle *;
 778
 779     PYBIND11_OBJECT_DEFAULT(iterator, object, PyIter_Check)
 780
 781     iterator& operator++() {
 782         advance();
 783         return *this;
 784     }
 785
 786     iterator operator++(int) {
 787         auto rv = *this;
 788         advance();
 789         return rv;
 790     }
 791
 792     reference operator*() const {
 793         if (m_ptr && !value.ptr()) {
 794             auto& self = const_cast<iterator &>(*this);
 795             self.advance();
 796         }
 797         return value;
 798     }
 799
 800     pointer operator->() const { operator*(); return &value; }
 801
 802     /** \rst
 803          The value which marks the end of the iteration. ``it == iterator::sentinel()``
 804          is equivalent to catching ``StopIteration`` in Python.
 805
 806          .. code-block:: cpp
 807
 808              void foo(py::iterator it) {
 809                  while (it != py::iterator::sentinel()) {
 810                     // use `*it`
 811                     ++it;
 812                  }
 813              }
 814     \endrst */
 815     static iterator sentinel() { return {}; }
 816
 817     friend bool operator==(const iterator &a, const iterator &b) { return a->ptr() == b->ptr(); }
 818     friend bool operator!=(const iterator &a, const iterator &b) { return a->ptr() != b->ptr(); }
 819
 820 private:
 821     void advance() {
 822         value = reinterpret_steal<object>(PyIter_Next(m_ptr));
 823         if (PyErr_Occurred()) { throw error_already_set(); }
 824     }
 825
 826 private:
 827     object value = {};
 828 };
 829
 830 class iterable : public object {
 831 public:
 832     PYBIND11_OBJECT_DEFAULT(iterable, object, detail::PyIterable_Check)
 833 };
 834
 835 class bytes;
 836
 837 class str : public object {
 838 public:
 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
 881 private:
 882     /// Return string representation -- always returns a new reference, even if already a str
 883     static PyObject *raw_str(PyObject *op) {
 884         PyObject *str_value = PyObject_Str(op);
 885 #if PY_MAJOR_VERSION < 3
 886         if (!str_value) throw error_already_set();
 887         PyObject *unicode = PyUnicode_FromEncodedObject(str_value, "utf-8", nullptr);
 888         Py_XDECREF(str_value); str_value = unicode;
 889 #endif
 890         return str_value;
 891     }
 892 };
 893 /// @} pytypes
 894
 895 inline namespace literals {
 896 /** \rst
 897     String literal version of `str`
 898  \endrst */
 899 inline str operator"" _s(const char *s, size_t size) { return {s, size}; }
 900 }
 901
 902 /// \addtogroup pytypes
 903 /// @{
 904 class bytes : public object {
 905 public:
 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
 933 inline bytes::bytes(const pybind11::str &s) {
 934     object temp = s;
 935     if (PyUnicode_Check(s.ptr())) {
 936         temp = reinterpret_steal<object>(PyUnicode_AsUTF8String(s.ptr()));
 937         if (!temp)
 938             pybind11_fail("Unable to extract string contents! (encoding issue)");
 939     }
 940     char *buffer;
 941     ssize_t length;
 942     if (PYBIND11_BYTES_AS_STRING_AND_SIZE(temp.ptr(), &buffer, &length))
 943         pybind11_fail("Unable to extract string contents! (invalid type)");
 944     auto obj = reinterpret_steal<object>(PYBIND11_BYTES_FROM_STRING_AND_SIZE(buffer, length));
 945     if (!obj)
 946         pybind11_fail("Could not allocate bytes object!");
 947     m_ptr = obj.release().ptr();
 948 }
 949
 950 inline str::str(const bytes& b) {
 951     char *buffer;
 952     ssize_t length;
 953     if (PYBIND11_BYTES_AS_STRING_AND_SIZE(b.ptr(), &buffer, &length))
 954         pybind11_fail("Unable to extract bytes contents!");
 955     auto obj = reinterpret_steal<object>(PyUnicode_FromStringAndSize(buffer, (ssize_t) length));
 956     if (!obj)
 957         pybind11_fail("Could not allocate string object!");
 958     m_ptr = obj.release().ptr();
 959 }
 960
 961 class none : public object {
 962 public:
 963     PYBIND11_OBJECT(none, object, detail::PyNone_Check)
 964     none() : object(Py_None, borrowed_t{}) { }
 965 };
 966
 967 class bool_ : public object {
 968 public:
 969     PYBIND11_OBJECT_CVT(bool_, object, PyBool_Check, raw_bool)
 970     bool_() : object(Py_False, borrowed_t{}) { }
 971     // Allow implicit conversion from and to `bool`:
 972     bool_(bool value) : object(value ? Py_True : Py_False, borrowed_t{}) { }
 973     operator bool() const { return m_ptr && PyLong_AsLong(m_ptr) != 0; }
 974
 975 private:
 976     /// Return the truth value of an object -- always returns a new reference
 977     static PyObject *raw_bool(PyObject *op) {
 978         const auto value = PyObject_IsTrue(op);
 979         if (value == -1) return nullptr;
 980         return handle(value ? Py_True : Py_False).inc_ref().ptr();
 981     }
 982 };
 983
 984 NAMESPACE_BEGIN(detail)
 985 // Converts a value to the given unsigned type.  If an error occurs, you get back (Unsigned) -1;
 986 // otherwise you get back the unsigned long or unsigned long long value cast to (Unsigned).
 987 // (The distinction is critically important when casting a returned -1 error value to some other
 988 // unsigned type: (A)-1 != (B)-1 when A and B are unsigned types of different sizes).
 989 template <typename Unsigned>
 990 Unsigned as_unsigned(PyObject *o) {
 991     if (sizeof(Unsigned) <= sizeof(unsigned long)
 992 #if PY_VERSION_HEX < 0x03000000
 993             || PyInt_Check(o)
 994 #endif
 995     ) {
 996         unsigned long v = PyLong_AsUnsignedLong(o);
 997         return v == (unsigned long) -1 && PyErr_Occurred() ? (Unsigned) -1 : (Unsigned) v;
 998     }
 999     else {
1000         unsigned long long v = PyLong_AsUnsignedLongLong(o);
1001         return v == (unsigned long long) -1 && PyErr_Occurred() ? (Unsigned) -1 : (Unsigned) v;
1002     }
1003 }
1004 NAMESPACE_END(detail)
1005
1006 class int_ : public object {
1007 public:
1008     PYBIND11_OBJECT_CVT(int_, object, PYBIND11_LONG_CHECK, PyNumber_Long)
1009     int_() : object(PyLong_FromLong(0), stolen_t{}) { }
1010     // Allow implicit conversion from C++ integral types:
1011     template <typename T,
1012               detail::enable_if_t<std::is_integral<T>::value, int> = 0>
1013     int_(T value) {
1014         if (sizeof(T) <= sizeof(long)) {
1015             if (std::is_signed<T>::value)
1016                 m_ptr = PyLong_FromLong((long) value);
1017             else
1018                 m_ptr = PyLong_FromUnsignedLong((unsigned long) value);
1019         } else {
1020             if (std::is_signed<T>::value)
1021                 m_ptr = PyLong_FromLongLong((long long) value);
1022             else
1023                 m_ptr = PyLong_FromUnsignedLongLong((unsigned long long) value);
1024         }
1025         if (!m_ptr) pybind11_fail("Could not allocate int object!");
1026     }
1027
1028     template <typename T,
1029               detail::enable_if_t<std::is_integral<T>::value, int> = 0>
1030     operator T() const {
1031         return std::is_unsigned<T>::value
1032             ? detail::as_unsigned<T>(m_ptr)
1033             : sizeof(T) <= sizeof(long)
1034               ? (T) PyLong_AsLong(m_ptr)
1035               : (T) PYBIND11_LONG_AS_LONGLONG(m_ptr);
1036     }
1037 };
1038
1039 class float_ : public object {
1040 public:
1041     PYBIND11_OBJECT_CVT(float_, object, PyFloat_Check, PyNumber_Float)
1042     // Allow implicit conversion from float/double:
1043     float_(float value) : object(PyFloat_FromDouble((double) value), stolen_t{}) {
1044         if (!m_ptr) pybind11_fail("Could not allocate float object!");
1045     }
1046     float_(double value = .0) : object(PyFloat_FromDouble((double) value), stolen_t{}) {
1047         if (!m_ptr) pybind11_fail("Could not allocate float object!");
1048     }
1049     operator float() const { return (float) PyFloat_AsDouble(m_ptr); }
1050     operator double() const { return (double) PyFloat_AsDouble(m_ptr); }
1051 };
1052
1053 class weakref : public object {
1054 public:
1055     PYBIND11_OBJECT_DEFAULT(weakref, object, PyWeakref_Check)
1056     explicit weakref(handle obj, handle callback = {})
1057         : object(PyWeakref_NewRef(obj.ptr(), callback.ptr()), stolen_t{}) {
1058         if (!m_ptr) pybind11_fail("Could not allocate weak reference!");
1059     }
1060 };
1061
1062 class slice : public object {
1063 public:
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
1079 class capsule : public object {
1080 public:
1081     PYBIND11_OBJECT_DEFAULT(capsule, object, PyCapsule_CheckExact)
1082     PYBIND11_DEPRECATED("Use reinterpret_borrow<capsule>() or reinterpret_steal<capsule>()")
1083     capsule(PyObject *ptr, bool is_borrowed) : object(is_borrowed ? object(ptr, borrowed_t{}) : object(ptr, stolen_t{})) { }
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
1132 class tuple : public object {
1133 public:
1134     PYBIND11_OBJECT_CVT(tuple, object, PyTuple_Check, PySequence_Tuple)
1135     explicit tuple(size_t size = 0) : object(PyTuple_New((ssize_t) size), stolen_t{}) {
1136         if (!m_ptr) pybind11_fail("Could not allocate tuple object!");
1137     }
1138     size_t size() const { return (size_t) PyTuple_Size(m_ptr); }
1139     detail::tuple_accessor operator[](size_t index) const { return {*this, index}; }
1140     detail::tuple_iterator begin() const { return {*this, 0}; }
1141     detail::tuple_iterator end() const { return {*this, PyTuple_GET_SIZE(m_ptr)}; }
1142 };
1143
1144 class dict : public object {
1145 public:
1146     PYBIND11_OBJECT_CVT(dict, object, PyDict_Check, raw_dict)
1147     dict() : object(PyDict_New(), stolen_t{}) {
1148         if (!m_ptr) pybind11_fail("Could not allocate dict object!");
1149     }
1150     template <typename... Args,
1151               typename = detail::enable_if_t<detail::all_of<detail::is_keyword_or_ds<Args>...>::value>,
1152               // MSVC workaround: it can't compile an out-of-line definition, so defer the collector
1153               typename collector = detail::deferred_t<detail::unpacking_collector<>, Args...>>
1154     explicit dict(Args &&...args) : dict(collector(std::forward<Args>(args)...).kwargs()) { }
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
1163 private:
1164     /// Call the `dict` Python type -- always returns a new reference
1165     static PyObject *raw_dict(PyObject *op) {
1166         if (PyDict_Check(op))
1167             return handle(op).inc_ref().ptr();
1168         return PyObject_CallFunctionObjArgs((PyObject *) &PyDict_Type, op, nullptr);
1169     }
1170 };
1171
1172 class sequence : public object {
1173 public:
1174     PYBIND11_OBJECT_DEFAULT(sequence, object, PySequence_Check)
1175     size_t size() const { return (size_t) PySequence_Size(m_ptr); }
1176     detail::sequence_accessor operator[](size_t index) const { return {*this, index}; }
1177     detail::sequence_iterator begin() const { return {*this, 0}; }
1178     detail::sequence_iterator end() const { return {*this, PySequence_Size(m_ptr)}; }
1179 };
1180
1181 class list : public object {
1182 public:
1183     PYBIND11_OBJECT_CVT(list, object, PyList_Check, PySequence_List)
1184     explicit list(size_t size = 0) : object(PyList_New((ssize_t) size), stolen_t{}) {
1185         if (!m_ptr) pybind11_fail("Could not allocate list object!");
1186     }
1187     size_t size() const { return (size_t) PyList_Size(m_ptr); }
1188     detail::list_accessor operator[](size_t index) const { return {*this, index}; }
1189     detail::list_iterator begin() const { return {*this, 0}; }
1190     detail::list_iterator end() const { return {*this, PyList_GET_SIZE(m_ptr)}; }
1191     template <typename T> void append(T &&val) const {
1192         PyList_Append(m_ptr, detail::object_or_cast(std::forward<T>(val)).ptr());
1193     }
1194 };
1195
1196 class args : public tuple { PYBIND11_OBJECT_DEFAULT(args, tuple, PyTuple_Check) };
1197 class kwargs : public dict { PYBIND11_OBJECT_DEFAULT(kwargs, dict, PyDict_Check)  };
1198
1199 class set : public object {
1200 public:
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
1212 class function : public object {
1213 public:
1214     PYBIND11_OBJECT_DEFAULT(function, object, PyCallable_Check)
1215     handle cpp_function() const {
1216         handle fun = detail::get_function(m_ptr);
1217         if (fun && PyCFunction_Check(fun.ptr()))
1218             return fun;
1219         return handle();
1220     }
1221     bool is_cpp_function() const { return (bool) cpp_function(); }
1222 };
1223
1224 class buffer : public object {
1225 public:
1226     PYBIND11_OBJECT_DEFAULT(buffer, object, PyObject_CheckBuffer)
1227
1228     buffer_info request(bool writable = false) {
1229         int flags = PyBUF_STRIDES | PyBUF_FORMAT;
1230         if (writable) flags |= PyBUF_WRITABLE;
1231         Py_buffer *view = new Py_buffer();
1232         if (PyObject_GetBuffer(m_ptr, view, flags) != 0) {
1233             delete view;
1234             throw error_already_set();
1235         }
1236         return buffer_info(view);
1237     }
1238 };
1239
1240 class memoryview : public object {
1241 public:
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 /// @{
1275 inline size_t len(handle h) {
1276     ssize_t result = PyObject_Length(h.ptr());
1277     if (result < 0)
1278         pybind11_fail("Unable to compute length of object");
1279     return (size_t) result;
1280 }
1281
1282 inline str repr(handle h) {
1283     PyObject *str_value = PyObject_Repr(h.ptr());
1284     if (!str_value) throw error_already_set();
1285 #if PY_MAJOR_VERSION < 3
1286     PyObject *unicode = PyUnicode_FromEncodedObject(str_value, "utf-8", nullptr);
1287     Py_XDECREF(str_value); str_value = unicode;
1288     if (!str_value) throw error_already_set();
1289 #endif
1290     return reinterpret_steal<str>(str_value);
1291 }
1292
1293 inline iterator iter(handle obj) {
1294     PyObject *result = PyObject_GetIter(obj.ptr());
1295     if (!result) { throw error_already_set(); }
1296     return reinterpret_steal<iterator>(result);
1297 }
1298 /// @} python_builtins
1299
1300 NAMESPACE_BEGIN(detail)
1301 template <typename D> iterator object_api<D>::begin() const { return iter(derived()); }
1302 template <typename D> iterator object_api<D>::end() const { return iterator::sentinel(); }
1303 template <typename D> item_accessor object_api<D>::operator[](handle key) const {
1304     return {derived(), reinterpret_borrow<object>(key)};
1305 }
1306 template <typename D> item_accessor object_api<D>::operator[](const char *key) const {
1307     return {derived(), pybind11::str(key)};
1308 }
1309 template <typename D> obj_attr_accessor object_api<D>::attr(handle key) const {
1310     return {derived(), reinterpret_borrow<object>(key)};
1311 }
1312 template <typename D> str_attr_accessor object_api<D>::attr(const char *key) const {
1313     return {derived(), key};
1314 }
1315 template <typename D> args_proxy object_api<D>::operator*() const {
1316     return args_proxy(derived().ptr());
1317 }
1318 template <typename D> template <typename T> bool object_api<D>::contains(T &&item) const {
1319     return attr("__contains__")(std::forward<T>(item)).template cast<bool>();
1320 }
1321
1322 template <typename D>
1323 pybind11::str object_api<D>::str() const { return pybind11::str(derived()); }
1324
1325 template <typename D>
1326 str_attr_accessor object_api<D>::doc() const { return attr("__doc__"); }
1327
1328 template <typename D>
1329 handle object_api<D>::get_type() const { return (PyObject *) Py_TYPE(derived().ptr()); }
1330
1331 NAMESPACE_END(detail)
1332 NAMESPACE_END(PYBIND11_NAMESPACE)