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)
template<typename T >
T	cast () const &
template<typename T >
T	cast () &&
template<>
void	cast () const &
template<>
void	cast () &&
PyObject *	ptr () const
	Return the underlying PyObject * pointer. More...
PyObject *&	ptr ()
const handle &	inc_ref () const &
const handle &	dec_ref () const &
template<typename T >
T	cast () 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

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() [1/2]

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() [2/2]

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()

~object ( )

inline

Destructor; automatically calls handle::dec_ref()

Definition at line 242 of file pytypes.h.

References handle::dec_ref().

Member Function Documentation

cast()

T cast ( ) const

inherited

Attempt to cast the Python object into the given C++ type. A cast_error will be throw upon failure.

Definition at line 1743 of file cast.h.

dec_ref()

const handle& dec_ref ( ) const &

inlineinherited

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.

inc_ref()

const handle& inc_ref ( ) const &

inlineinherited

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()

operator bool ( ) const

inlineexplicitinherited

Return true when the handle wraps a valid Python object.

Definition at line 207 of file pytypes.h.

operator==()

bool operator== ( const handle &  h ) const

inlineinherited

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

Definition at line 213 of file pytypes.h.

ptr()

PyObject* ptr ( ) const

inlineinherited

Return the underlying PyObject * pointer.

Definition at line 184 of file pytypes.h.

release()

handle release ( )

inline

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

reinterpret_borrow

T reinterpret_borrow ( handle  h )

friend

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.

reinterpret_steal

T reinterpret_steal ( handle  h )

friend

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 files:

• pytypes.h
• cast.h