HepMC3 event record library
Data Structures | Public Member Functions | Data Fields | Protected Attributes | Friends
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 ()
 
objectoperator= (const object &other)
 
objectoperator= (object &&other) noexcept
 
template<typename T >
cast () const &
 
template<typename T >
cast () &&
 
 object (handle h, borrowed_t)
 
 object (handle h, stolen_t)
 
template<typename T >
cast () const &
 
template<typename T >
cast () &&
 
template<>
void cast () const &
 
template<>
void cast () &&
 
PyObject * ptr () const
 Return the underlying PyObject * pointer. More...
 
PyObject *& ptr ()
 
const handleinc_ref () const &
 
const handledec_ref () const &
 
template<typename 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 >
reinterpret_borrow (handle)
 
template<typename 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. \endrst

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
inherited

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

Definition at line 1743 of file cast.h.

◆ dec_ref()

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. \endrst

Definition at line 199 of file pytypes.h.

◆ inc_ref()

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. \endrst

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

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

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

\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. \endrst

Definition at line 249 of file pytypes.h.

References handle::handle().

Friends And Related Function Documentation

◆ reinterpret_borrow

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 \endrst

Definition at line 304 of file pytypes.h.

◆ reinterpret_steal

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 \endrst

Definition at line 314 of file pytypes.h.


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