object Class Reference

#include <pytypes.h>

Inheritance diagram for object:

Collaboration diagram for object:

Data Structures
struct	borrowed_t
struct	stolen_t

Public Member Functions
	PYBIND11_DEPRECATED ("Use reinterpret_borrow<object>() or reinterpret_steal<object>()") object(handle h
	object (const object &o)
	Copy constructor; always increases the reference count. More...
	object (object &&other) noexcept
	Move constructor; steals the object from other and preserves its reference count. More...
	~object ()
	Destructor; automatically calls handle::dec_ref() More...
handle	release ()
object &	operator= (const object &other)
object &	operator= (object &&other) noexcept
template<typename T >
T	cast () const &
template<typename T >
T	cast ()&&
	object (handle h, borrowed_t)
	object (handle h, stolen_t)
PyObject *	ptr () const
	Return the underlying PyObject * pointer. More...
PyObject *&	ptr ()
const handle &	inc_ref () const &
const handle &	dec_ref () const &
	operator bool () const
	Return true when the handle wraps a valid Python object. More...
bool	operator== (const handle &h) const
bool	operator!= (const handle &h) const
bool	check () const

Data Fields
bool	is_borrowed: handle(h) { if (is_borrowed) inc_ref()

Protected Attributes
PyObject *	m_ptr = nullptr

Friends
template<typename T >
T	reinterpret_borrow (handle)
template<typename T >
T	reinterpret_steal (handle)

Detailed Description

\rst
Holds a reference to a Python object (with reference counting)

Like `handle`, the `object` class is a thin wrapper around an arbitrary Python
object (i.e. a ``PyObject *`` in Python's C API). In contrast to `handle`, it
optionally increases the object's reference count upon construction, and it
 always* decreases the reference count when the `object` instance goes out of
scope and is destructed. When using `object` instances consistently, it is much
easier to get reference counting right at the first attempt.

Definition at line 232 of file pytypes.h.

Constructor & Destructor Documentation

object ( const object &  o )

inline

Copy constructor; always increases the reference count.

Definition at line 238 of file pytypes.h.

References handle::inc_ref().

object ( object &&  other )

inlinenoexcept

Move constructor; steals the object from other and preserves its reference count.

Definition at line 240 of file pytypes.h.

~object ( )

inline

Destructor; automatically calls handle::dec_ref()

Definition at line 242 of file pytypes.h.

References handle::dec_ref().

Member Function Documentation

const handle& dec_ref ( ) const

inlineinherited

\rst
Manually decrease the reference count of the Python object. Usually, it is
preferable to use the `object` class which derives from `handle` and calls
this function automatically. Returns a reference to itself.

Definition at line 199 of file pytypes.h.

const handle& inc_ref ( ) const

inlineinherited

\rst
Manually increase the reference count of the Python object. Usually, it is
preferable to use the `object` class which derives from `handle` and calls
this function automatically. Returns a reference to itself.

Definition at line 192 of file pytypes.h.

operator bool ( ) const

inlineexplicitinherited

Return true when the handle wraps a valid Python object.

Definition at line 207 of file pytypes.h.

bool operator== ( const handle &  h ) const

inlineinherited

\rst
Deprecated: Check that the underlying pointers are the same.
Equivalent to ``obj1 is obj2`` in Python.

Definition at line 213 of file pytypes.h.

PyObject* ptr ( ) const

inlineinherited

Return the underlying PyObject * pointer.

Definition at line 184 of file pytypes.h.

handle release ( )

inline

\rst
Resets the internal pointer to ``nullptr`` without decreasing the
object's reference count. The function returns a raw handle to the original
Python object.

Definition at line 249 of file pytypes.h.

References handle::handle().

Friends And Related Function Documentation

T reinterpret_borrow ( handle  h )

friend

\rst
Declare that a `handle` or ``PyObject *`` is a certain type and borrow the reference.
The target type ``T`` must be `object` or one of its derived classes. The function
doesn't do any conversions or checks. It's up to the user to make sure that the
target type is correct.

.. code-block:: cpp

    PyObject *p = PyList_GetItem(obj, index);
    py::object o = reinterpret_borrow<py::object>(p);

or py::tuple t = reinterpret_borrow<py::tuple>(p); // <– p must be already be a tuple

Definition at line 304 of file pytypes.h.

T reinterpret_steal ( handle  h )

friend

\rst
Like `reinterpret_borrow`, but steals the reference.

 .. code-block:: cpp

    PyObject *p = PyObject_Str(obj);
    py::str s = reinterpret_steal<py::str>(p); // <-- `p` must be already be a `str`

Definition at line 314 of file pytypes.h.

---

The documentation for this class was generated from the following file:

• pytypes.h