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)
 
PyObject * ptr () const
 Return the underlying PyObject * pointer. More...
 
PyObject *& ptr ()
 
const handleinc_ref () const &
 
const handledec_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 >
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.

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: