include/pybind11/pytypes.h

20 class handle; class object;
26 inline bool isinstance_generic(handle obj, const std::type_info &tp);
50     A mixin class which adds common functions to `handle`, `object` and various accessors.
68         the returned ``detail::item_accessor`` instance to a `handle` or `object`
69         subclass causes a corresponding call to ``__getitem__``. Assigning a `handle`
72     item_accessor operator[](handle key) const;
78         returned ``detail::obj_attr_accessor`` instance to a `handle` or `object`
79         subclass causes a corresponding call to ``getattr``. Assigning a `handle`
82     obj_attr_accessor attr(handle key) const;
101         may need to be converted back into a Python object using `handle::cast()`.
154     /// Return a handle to the Python type object underlying the instance
155     handle get_type() const;
166     The `handle` class is a thin wrapper around an arbitrary Python object (i.e. a
171         The `object` class inherits from `handle` and adds automatic reference
174 class handle : public detail::object_api<handle> {
176     /// The default constructor creates a handle with a ``nullptr``-valued pointer
177     handle() = default;
178     /// Creates a ``handle`` from the given raw Python object pointer
179     handle(PyObject *ptr) : m_ptr(ptr) { } // Allow implicit conversion from PyObject*
187         preferable to use the `object` class which derives from `handle` and calls
190     const handle& inc_ref() const & { Py_XINCREF(m_ptr); return *this; }
194         preferable to use the `object` class which derives from `handle` and calls
197     const handle& dec_ref() const & { Py_XDECREF(m_ptr); return *this; }
204     /// Return ``true`` when the `handle` wraps a valid Python object
211     bool operator==(const handle &h) const { return m_ptr == h.m_ptr; }
213     bool operator!=(const handle &h) const { return m_ptr != h.m_ptr; }
214     PYBIND11_DEPRECATED("Use handle::operator bool() instead")
223     Like `handle`, the `object` class is a thin wrapper around an arbitrary Python
224     object (i.e. a ``PyObject *`` in Python's C API). In contrast to `handle`, it
230 class object : public handle {
234     object(handle h, bool is_borrowed) : handle(h) { if (is_borrowed) inc_ref(); }
236     object(const object &o) : handle(o) { inc_ref(); }
239     /// Destructor; automatically calls `handle::dec_ref()`
244         object's reference count. The function returns a raw handle to the original
247     handle release() {
250       return handle(tmp);
262             handle temp(m_ptr);
270     // Calling cast() on an object lvalue just copies (via handle::cast)
280     template <typename T> friend T reinterpret_borrow(handle);
281     template <typename T> friend T reinterpret_steal(handle);
285     object(handle h, borrowed_t) : handle(h) { inc_ref(); }
286     object(handle h, stolen_t) : handle(h) { }
290     Declare that a `handle` or ``PyObject *`` is a certain type and borrow the reference.
302 template <typename T> T reinterpret_borrow(handle h) { return {h, object::borrowed_t{}}; }
312 template <typename T> T reinterpret_steal(handle h) { return {h, object::stolen_t{}}; }
347     bool matches(handle exc) const { return PyErr_GivenExceptionMatches(m_type.ptr(), exc.ptr()); }
368 bool isinstance(handle obj) { return T::check_(obj); }
371 bool isinstance(handle obj) { return detail::isinstance_generic(obj, typeid(T)); }
373 template <> inline bool isinstance<handle>(handle obj) = delete;
374 template <> inline bool isinstance<object>(handle obj) { return obj.ptr() != nullptr; }
378 inline bool isinstance(handle obj, handle type) {
387 inline bool hasattr(handle obj, handle name) {
391 inline bool hasattr(handle obj, const char *name) {
395 inline void delattr(handle obj, handle name) {
399 inline void delattr(handle obj, const char *name) {
403 inline object getattr(handle obj, handle name) {
409 inline object getattr(handle obj, const char *name) {
415 inline object getattr(handle obj, handle name, handle default_) {
424 inline object getattr(handle obj, const char *name, handle default_) {
433 inline void setattr(handle obj, handle name, handle value) {
437 inline void setattr(handle obj, const char *name, handle value) {
441 inline ssize_t hash(handle obj) {
450 inline handle get_function(handle value) {
471 // Match a PyObject*, which we want to convert directly to handle via its converting constructor
472 inline handle object_or_cast(PyObject *ptr) { return ptr; }
479     accessor(handle obj, key_type key) : obj(obj), key(std::move(key)) { }
485     void operator=(const accessor &a) && { std::move(*this).operator=(handle(a)); }
486     void operator=(const accessor &a) & { operator=(handle(a)); }
518     handle obj;
526     static object get(handle obj, handle key) { return getattr(obj, key); }
527     static void set(handle obj, handle key, handle val) { setattr(obj, key, val); }
532     static object get(handle obj, const char *key) { return getattr(obj, key); }
533     static void set(handle obj, const char *key, handle val) { setattr(obj, key, val); }
539     static object get(handle obj, handle key) {
545     static void set(handle obj, handle key, handle val) {
553     static object get(handle obj, size_t index) {
559     static void set(handle obj, size_t index, handle val) {
570     static object get(handle obj, size_t index) {
576     static void set(handle obj, size_t index, handle val) {
587     static object get(handle obj, size_t index) {
593     static void set(handle obj, size_t index, handle val) {
615     generic_iterator(handle seq, ssize_t index) : Policy(seq, index) { }
655     using value_type = handle;
656     using reference = const handle;
657     using pointer = arrow_proxy<const handle>;
659     sequence_fast_readonly(handle obj, ssize_t n) : ptr(PySequence_Fast_ITEMS(obj.ptr()) + n) { }
680     sequence_slow_readwrite(handle obj, ssize_t index) : obj(obj), index(index) { }
690     handle obj;
698     using value_type = std::pair<handle, handle>;
703     dict_readonly(handle obj, ssize_t pos) : obj(obj), pos(pos) { increment(); }
710     handle obj;
747 class kwargs_proxy : public handle {
749     explicit kwargs_proxy(handle h) : handle(h) { }
752 class args_proxy : public handle {
754     explicit args_proxy(handle h) : handle(h) { }
782         Name(handle h, bool is_borrowed) : Parent(is_borrowed ? Parent(h, borrowed_t{}) : Parent(h, stolen_t{})) { } \
783         Name(handle h, borrowed_t) : Parent(h, borrowed_t{}) { } \
784         Name(handle h, stolen_t) : Parent(h, stolen_t{}) { } \
787         static bool check_(handle h) { return h.ptr() != nullptr && CheckFun(h.ptr()); }
826     using value_type = handle;
827     using reference = const handle;
828     using pointer = const handle *;
911     explicit str(handle h) : object(raw_str(h.ptr()), stolen_t{}) { }
1039         return handle(value ? Py_True : Py_False).inc_ref().ptr();
1115     explicit weakref(handle obj, handle callback = {})
1207     detail::item_accessor operator[](handle h) const { return object::operator[](h); }
1237             return handle(op).inc_ref().ptr();
1248     detail::item_accessor operator[](handle h) const { return object::operator[](h); }
1262     detail::item_accessor operator[](handle h) const { return object::operator[](h); }
1297     handle cpp_function() const {
1298         handle fun = detail::get_function(m_ptr);
1301         return handle();
1362 inline size_t len(handle h) {
1369 inline size_t len_hint(handle h) {
1384 inline str repr(handle h) {
1395 inline iterator iter(handle obj) {
1405 template <typename D> item_accessor object_api<D>::operator[](handle key) const {
1411 template <typename D> obj_attr_accessor object_api<D>::attr(handle key) const {
1431 handle object_api<D>::get_type() const { return (PyObject *) Py_TYPE(derived().ptr()); }