handle Class Reference

\rst Holds a reference to a Python object (no reference counting) More...

#include </builds/ipbus/ipbus-software/uhal/python/pybind11-python2/include/pybind11/pytypes.h>

Inheritance diagram for handle:

Collaboration diagram for handle:

Public Member Functions
	handle ()=default
	The default constructor creates a handle with a nullptr-valued pointer. More...
	handle (PyObject *ptr)
	Creates a handle from the given raw Python object pointer. More...
PyObject *	ptr () const
	Return the underlying PyObject * pointer. More...
PyObject *&	ptr ()
const handle &	inc_ref () const &
	\rst Manually increase the reference count of the Python object. More...
const handle &	dec_ref () const &
	\rst Manually decrease the reference count of the Python object. More...
template<typename T >
T	cast () const
	\rst Attempt to cast the Python object into the given C++ type. More...
	operator bool () const
	Return true when the handle wraps a valid Python object. More...
bool	operator== (const handle &h) const
	\rst Deprecated: Check that the underlying pointers are the same. More...
bool	operator!= (const handle &h) const
bool	check () const
	handle ()=default
	The default constructor creates a handle with a nullptr-valued pointer. More...
template<typename T , detail::enable_if_t< detail::is_pyobj_ptr_or_nullptr_t< T >::value, int > = 0>
	handle (T ptr)
	Enable implicit conversion from PyObject * and nullptr. More...
template<typename T , detail::enable_if_t< detail::all_of< detail::none_of< std::is_base_of< handle, T >, detail::is_pyobj_ptr_or_nullptr_t< T > >, std::is_convertible< T, PyObject * > >::value, int > = 0>
	handle (T &obj)
	Enable implicit conversion through T::operator PyObject *(). More...
PyObject *	ptr () const
	Return the underlying PyObject * pointer. More...
PyObject *&	ptr ()
const handle &	inc_ref () const &
	\rst Manually increase the reference count of the Python object. More...
const handle &	dec_ref () const &
	\rst Manually decrease the reference count of the Python object. More...
template<typename T >
T	cast () const
	\rst Attempt to cast the Python object into the given C++ type. More...
	operator bool () const
	Return true when the handle wraps a valid Python object. More...
bool	operator== (const handle &h) const
	\rst Deprecated: Check that the underlying pointers are the same. More...
bool	operator!= (const handle &h) const
bool	check () const
template<>
void	cast () const

Static Public Member Functions
static std::size_t	inc_ref_counter ()

Protected Attributes
PyObject *	m_ptr = nullptr

Static Private Member Functions
static std::size_t	inc_ref_counter (std::size_t add)

Detailed Description

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

The handle class is a thin wrapper around an arbitrary Python object (i.e. a PyObject * in Python's C API). It does not perform any automatic reference counting and merely provides a basic C++ interface to various Python API functions.

.. seealso:: The object class inherits from handle and adds automatic reference counting features. \endrst

The handle class is a thin wrapper around an arbitrary Python object (i.e. a PyObject * in Python's C API). It does not perform any automatic reference counting and merely provides a basic C++ interface to various Python API functions.

.. seealso:: The object class inherits from handle and adds automatic reference counting features. \endrst

Definition at line 194 of file pytypes.h.

Constructor & Destructor Documentation

handle() [1/5]

handle::handle ( )

default

The default constructor creates a handle with a nullptr-valued pointer.

Referenced by cpp_function::dispatcher(), and object::release().

handle() [2/5]

handle::handle ( PyObject *  ptr )

inline

Creates a handle from the given raw Python object pointer.

Definition at line 200 of file pytypes.h.

handle() [3/5]

handle::handle ( )

default

The default constructor creates a handle with a nullptr-valued pointer.

handle() [4/5]

template<typename T , detail::enable_if_t< detail::is_pyobj_ptr_or_nullptr_t< T >::value, int > = 0>

handle::handle ( T  ptr )

inline

Enable implicit conversion from PyObject * and nullptr.

Not using handle(PyObject *ptr) to avoid implicit conversion from 0.

Definition at line 227 of file pytypes.h.

handle() [5/5]

template<typename T , detail::enable_if_t< detail::all_of< detail::none_of< std::is_base_of< handle, T >, detail::is_pyobj_ptr_or_nullptr_t< T > >, std::is_convertible< T, PyObject * > >::value, int > = 0>

handle::handle ( T &  obj )

inline

Enable implicit conversion through T::operator PyObject *().

Definition at line 238 of file pytypes.h.

Member Function Documentation

cast() [1/3]

template<>

void handle::cast ( ) const

inline

Definition at line 1087 of file cast.h.

cast() [2/3]

template<typename T >

T handle::cast

\rst Attempt to cast the Python object into the given C++ type.

A cast_error will be throw upon failure. \endrst

Definition at line 1083 of file cast.h.

Referenced by error_string(), error_fetch_and_normalize::format_value_and_trace(), get_fully_qualified_tp_name(), cpp_function::initialize_generic(), type_caster< MoveOnlyInt >::load(), type_caster< MoveOrCopyInt >::load(), type_caster< CopyOnlyInt >::load(), make_new_python_type(), and type_info_description().

cast() [3/3]

template<typename T >

T handle::cast

(

)

const

\rst Attempt to cast the Python object into the given C++ type.

A cast_error will be throw upon failure. \endrst

check() [1/2]

bool handle::check ( ) const

inline

Definition at line 243 of file pytypes.h.

check() [2/2]

bool handle::check ( ) const

inline

Definition at line 294 of file pytypes.h.

References m_ptr.

dec_ref() [1/2]

const handle & handle::dec_ref ( ) const &

inline

\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 221 of file pytypes.h.

Referenced by all_type_info_get_cache(), class_< type_, options >::def_buffer(), keep_alive_impl(), object::operator=(), error_already_set::~error_already_set(), and object::~object().

dec_ref() [2/2]

const handle & handle::dec_ref ( ) const &

inline

\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 267 of file pytypes.h.

References m_ptr.

inc_ref() [1/2]

const handle & handle::inc_ref ( ) const &

inline

\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 211 of file pytypes.h.

Referenced by module_::add_object(), type_caster< bool >::cast(), type_caster< CharT, enable_if_t< is_std_char_type< CharT >::value > >::cast(), pyobject_caster< type >::cast(), pyobject_caster< array_t< T, ExtraFlags > >::cast(), type_caster< void >::cast(), type_caster< std::function< Return(Args...)> >::cast(), optional_caster< Type, Value >::cast(), void_caster< T >::cast(), cpp_function::dispatcher(), find_registered_python_instance(), process_attribute< arg_v >::init(), cpp_function::initialize_generic(), object::object(), object::operator=(), object::PYBIND11_DEPRECATED(), bool_::raw_bool(), dict::raw_dict(), error_fetch_and_normalize::restore(), list_item::set(), and tuple_item::set().

inc_ref() [2/2]

const handle & handle::inc_ref ( ) const &

inline

\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 249 of file pytypes.h.

References inc_ref_counter(), and m_ptr.

inc_ref_counter() [1/2]

static std::size_t handle::inc_ref_counter ( )

inlinestatic

Definition at line 328 of file pytypes.h.

References inc_ref_counter().

Referenced by inc_ref(), and inc_ref_counter().

inc_ref_counter() [2/2]

static std::size_t handle::inc_ref_counter ( std::size_t  add )

inlinestaticprivate

Definition at line 321 of file pytypes.h.

operator bool() [1/2]

handle::operator bool ( ) const

inlineexplicit

Return true when the handle wraps a valid Python object.

Definition at line 233 of file pytypes.h.

operator bool() [2/2]

handle::operator bool ( ) const

inlineexplicit

Return true when the handle wraps a valid Python object.

Definition at line 284 of file pytypes.h.

References m_ptr.

operator!=() [1/2]

bool handle::operator!= ( const handle &  h ) const

inline

Definition at line 241 of file pytypes.h.

operator!=() [2/2]

bool handle::operator!= ( const handle &  h ) const

inline

Definition at line 292 of file pytypes.h.

References m_ptr.

operator==() [1/2]

bool handle::operator== ( const handle &  h ) const

inline

\rst Deprecated: Check that the underlying pointers are the same.

Equivalent to obj1 is obj2 in Python. \endrst

Definition at line 239 of file pytypes.h.

operator==() [2/2]

bool handle::operator== ( const handle &  h ) const

inline

\rst Deprecated: Check that the underlying pointers are the same.

Equivalent to obj1 is obj2 in Python. \endrst

Definition at line 290 of file pytypes.h.

References m_ptr.

ptr() [1/4]

PyObject *& handle::ptr ( )

inline

Definition at line 204 of file pytypes.h.

ptr() [2/4]

PyObject *& handle::ptr ( )

inline

Definition at line 242 of file pytypes.h.

References m_ptr.

ptr() [3/4]

PyObject * handle::ptr ( ) const

inline

Return the underlying PyObject * pointer.

Definition at line 203 of file pytypes.h.

Referenced by dtype::_dtype_from_pep3118(), set::add(), module_::add_object(), loader_life_support::add_patient(), iterator::advance(), list::append(), array::array(), bytes::bytes(), simple_collector< policy >::call(), unpacking_collector< policy >::call(), list_caster< Type, Value >::cast(), array_caster< ArrayType, Value, Resizable, Size >::cast(), array_t< T, ExtraFlags >::check_(), dict::clear(), dict::contains(), set::contains(), anyset::contains(), function::cpp_function(), generic_type::def_property_static_impl(), delattr(), error_already_set::discard_as_unraisable(), cpp_function::dispatcher(), dtype::dtype(), eigen_array_cast(), array_t< T, ExtraFlags >::ensure(), array::ensure(), error_fetch_and_normalize::error_fetch_and_normalize(), eval(), eval_file(), error_fetch_and_normalize::format_value_and_trace(), dtype::from_args(), memoryview::from_buffer(), memoryview::from_memory(), sequence_item::get(), list_item::get(), tuple_item::get(), generic_item::get(), class_< type_, options >::get_function_record(), get_type_override(), getattr(), hasattr(), hash(), implicitly_convertible(), dict_readonly::increment(), multi_array_iterator< N >::init_common_iterator(), generic_type::initialize(), cpp_function::initialize_generic(), list::insert(), isinstance(), isinstance< object >(), iter(), len(), len_hint(), type_caster< void >::load(), type_caster< value_and_holder >::load(), type_caster< T, enable_if_t< std::is_arithmetic< T >::value &&!is_std_char_type< T >::value > >::load(), type_caster< bool >::load(), type_caster< std::complex< T > >::load(), string_caster< StringType, IsView >::load(), pyobject_caster< type >::load(), duration_caster< type >::load(), type_caster< std::chrono::time_point< std::chrono::system_clock, Duration > >::load(), type_caster_generic::load_impl(), make_new_python_type(), error_already_set::matches(), error_fetch_and_normalize::matches(), str::operator std::string(), iterator::operator*(), pybind11_getbuffer(), array::raw_array(), array_t< T, ExtraFlags >::raw_array_t(), bool_::raw_bool(), dict::raw_dict(), module_::reload(), repr(), error_fetch_and_normalize::restore(), sequence_item::set(), list_item::set(), tuple_item::set(), generic_item::set(), setattr(), str::str(), type_caster_generic::try_direct_conversions(), type_caster_generic::try_load_foreign_module_local(), and array::view().

ptr() [4/4]

PyObject * handle::ptr ( ) const

inline

Return the underlying PyObject * pointer.

Definition at line 241 of file pytypes.h.

References m_ptr.

Member Data Documentation

m_ptr

PyObject * handle::m_ptr = nullptr

protected

Definition at line 246 of file pytypes.h.

Referenced by set::add(), iterator::advance(), dtype::alignment(), list::append(), array::array(), array_t< T, ExtraFlags >::array_t(), array::base(), bytearray::bytearray(), dtype::byteorder(), bytes::bytes(), dtype::char_(), check(), set::clear(), slice::compute(), dict::contains(), set::contains(), anyset::contains(), function::cpp_function(), array::data(), dec_ref(), module_::def_submodule(), array::dtype(), dtype::dtype(), tuple::end(), list::end(), exception< type >::exception(), array::flags(), dtype::flags(), float_::float_(), dtype::has_fields(), inc_ref(), cpp_function::initialize_generic(), list::insert(), int_::int_(), array::itemsize(), dtype::itemsize(), dtype::kind(), list::list(), memoryview::memoryview(), array::mutable_data(), array::ndim(), dtype::num(), object::object(), bool_::operator bool(), operator bool(), float_::operator double(), float_::operator float(), str::operator std::string(), bytes::operator std::string(), bytearray::operator std::string(), int_::operator T(), operator!=(), exception< type >::operator()(), iterator::operator*(), object::operator=(), operator==(), array::owndata(), ptr(), object::release(), buffer::request(), array::reshape(), array::resize(), array::shape(), bytearray::size(), tuple::size(), dict::size(), set::size(), list::size(), anyset::size(), slice::slice(), array::squeeze(), str::str(), array::strides(), bytes::string_op(), tuple::tuple(), array::view(), and array::writeable().

---

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

• python/pybind11-python2/include/pybind11/pytypes.h
• python/pybind11/include/pybind11/pytypes.h
• python/pybind11-python2/include/pybind11/cast.h
• python/pybind11/include/pybind11/cast.h