Fetch and hold an error which was already set in Python. More...

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

Inheritance diagram for error_already_set:

Collaboration diagram for error_already_set:

Public Member Functions
	error_already_set ()
	Constructs a new exception from the current Python error indicator, if any. More...

	error_already_set (const error_already_set &)=default

	error_already_set (error_already_set &&)=default

	~error_already_set () override

void	restore ()
	Give the currently-held error back to Python, if any. More...

void	discard_as_unraisable (object err_context)
	If it is impossible to raise the currently-held error, such as in a destructor, we can write it out using Python's unraisable hook (`sys.unraisablehook`). More...

void	discard_as_unraisable (const char *err_context)
	An alternate version of `discard_as_unraisable()`, where a string provides information on the location of the error. More...

void	clear ()

bool	matches (handle exc) const
	Check if the currently trapped error type matches the given Python exception class (or a subclass thereof). More...

const object &	type () const

const object &	value () const

const object &	trace () const

	error_already_set ()
	Fetches the current Python exception (using PyErr_Fetch()), which will clear the current Python error indicator. More...

const char *	what () const noexcept override
	The what() result is built lazily on demand. More...

void	restore ()
	Restores the currently-held Python error (which will clear the Python error indicator first if already set). More...

void	discard_as_unraisable (object err_context)
	If it is impossible to raise the currently-held error, such as in a destructor, we can write it out using Python's unraisable hook (`sys.unraisablehook`). More...

void	discard_as_unraisable (const char *err_context)
	An alternate version of `discard_as_unraisable()`, where a string provides information on the location of the error. More...

void	clear ()

bool	matches (handle exc) const
	Check if the currently trapped error type matches the given Python exception class (or a subclass thereof). More...

const object &	type () const

const object &	value () const

const object &	trace () const

Static Private Member Functions
static void	m_fetched_error_deleter (detail::error_fetch_and_normalize *raw_ptr)
	WARNING: This custom deleter needs to acquire the Python GIL. More...

Private Attributes
object	m_type

object	m_value

object	m_trace

std::shared_ptr< detail::error_fetch_and_normalize >	m_fetched_error

Detailed Description

Fetch and hold an error which was already set in Python.

An instance of this is typically thrown to propagate python-side errors back through C++ which can either be caught manually or else falls back to the function dispatcher (which then raises the captured error back to python).

Definition at line 379 of file pytypes.h.

Constructor & Destructor Documentation

◆ error_already_set() [1/4]

error_already_set::error_already_set ( )

inline

Constructs a new exception from the current Python error indicator, if any.

The current Python error indicator will be cleared.

Definition at line 383 of file pytypes.h.

◆ error_already_set() [2/4]

error_already_set::error_already_set ( const error_already_set & )

default

◆ error_already_set() [3/4]

error_already_set::error_already_set ( error_already_set && )

default

◆ ~error_already_set()

error_already_set::~error_already_set ( )

inlineoverride

Definition at line 2639 of file pybind11.h.

References handle::dec_ref(), m_trace, m_type, m_value, and object::release().

◆ error_already_set() [4/4]

error_already_set::error_already_set ( )

inline

Fetches the current Python exception (using PyErr_Fetch()), which will clear the current Python error indicator.

Definition at line 667 of file pytypes.h.

Member Function Documentation

◆ clear() [1/2]

void error_already_set::clear ( )

inline

Definition at line 417 of file pytypes.h.

◆ clear() [2/2]

void error_already_set::clear ( )

inline

Definition at line 700 of file pytypes.h.

◆ discard_as_unraisable() [1/4]

void error_already_set::discard_as_unraisable ( const char * err_context )

inline

An alternate version of discard_as_unraisable(), where a string provides information on the location of the error.

For example, __func__ could be helpful.

Definition at line 411 of file pytypes.h.

References PYBIND11_FROM_STRING.

◆ discard_as_unraisable() [2/4]

void error_already_set::discard_as_unraisable ( const char * err_context )

inline

An alternate version of discard_as_unraisable(), where a string provides information on the location of the error.

For example, __func__ could be helpful. WARNING: The GIL must be held when this member function is called!

Definition at line 694 of file pytypes.h.

References PYBIND11_FROM_STRING.

◆ discard_as_unraisable() [3/4]

void error_already_set::discard_as_unraisable ( object err_context )

inline

If it is impossible to raise the currently-held error, such as in a destructor, we can write it out using Python's unraisable hook (sys.unraisablehook).

The error context should be some object whose repr() helps identify the location of the error. Python already knows the type and value of the error, so there is no need to repeat that. After this call, the current object no longer stores the error variables, and neither does Python.

Definition at line 405 of file pytypes.h.

References handle::ptr().

◆ discard_as_unraisable() [4/4]

void error_already_set::discard_as_unraisable ( object err_context )

inline

If it is impossible to raise the currently-held error, such as in a destructor, we can write it out using Python's unraisable hook (sys.unraisablehook).

The error context should be some object whose repr() helps identify the location of the error. Python already knows the type and value of the error, so there is no need to repeat that.

Definition at line 687 of file pytypes.h.

References handle::ptr().

◆ m_fetched_error_deleter()

void error_already_set::m_fetched_error_deleter ( detail::error_fetch_and_normalize * raw_ptr )

inlinestaticprivate

WARNING: This custom deleter needs to acquire the Python GIL.

This can lead to crashes (undefined behavior) if the Python interpreter is finalizing.

Definition at line 2651 of file pybind11.h.

◆ matches() [1/2]

bool error_already_set::matches ( handle exc ) const

inline

Check if the currently trapped error type matches the given Python exception class (or a subclass thereof).

May also be passed a tuple to search for any exception class matches in the given tuple.

Definition at line 422 of file pytypes.h.

References handle::ptr().

◆ matches() [2/2]

bool error_already_set::matches ( handle exc ) const

inline

Check if the currently trapped error type matches the given Python exception class (or a subclass thereof).

May also be passed a tuple to search for any exception class matches in the given tuple.

Definition at line 705 of file pytypes.h.

◆ restore() [1/2]

void error_already_set::restore ( )

inline

Give the currently-held error back to Python, if any.

If there is currently a Python error already set it is cleared first. After this call, the current object no longer stores the error variables (but the .what() string is still available).

Definition at line 395 of file pytypes.h.

Referenced by cpp_function::dispatcher(), raise_from(), translate_exception(), and translate_local_exception().

◆ restore() [2/2]

void error_already_set::restore ( )

inline

Restores the currently-held Python error (which will clear the Python error indicator first if already set).

NOTE: This member function will always restore the normalized exception, which may or may not be the original Python exception. WARNING: The GIL must be held when this member function is called!

Definition at line 681 of file pytypes.h.

References error_fetch_and_normalize::restore().

◆ trace() [1/2]

const object & error_already_set::trace ( ) const

inline

Definition at line 428 of file pytypes.h.

◆ trace() [2/2]

const object & error_already_set::trace ( ) const

inline

Definition at line 709 of file pytypes.h.

◆ type() [1/2]

const object & error_already_set::type ( ) const

inline

Definition at line 426 of file pytypes.h.

◆ type() [2/2]

const object & error_already_set::type ( ) const

inline

Definition at line 707 of file pytypes.h.

◆ value() [1/2]

const object & error_already_set::value ( ) const

inline

Definition at line 427 of file pytypes.h.

◆ value() [2/2]

const object & error_already_set::value ( ) const

inline

Definition at line 708 of file pytypes.h.

◆ what()

const char * error_already_set::what ( ) const

inlineoverridenoexcept

The what() result is built lazily on demand.

WARNING: This member function needs to acquire the Python GIL. This can lead to crashes (undefined behavior) if the Python interpreter is finalizing.

Definition at line 2657 of file pybind11.h.

References m_fetched_error.

Referenced by translate_exception().

Member Data Documentation

◆ m_fetched_error

std::shared_ptr<detail::error_fetch_and_normalize> error_already_set::m_fetched_error

private

Definition at line 712 of file pytypes.h.

Referenced by what().

◆ m_trace

object error_already_set::m_trace

private

Definition at line 431 of file pytypes.h.

Referenced by ~error_already_set().

◆ m_type

object error_already_set::m_type

private

Definition at line 431 of file pytypes.h.

Referenced by ~error_already_set().

◆ m_value

object error_already_set::m_value

private

Definition at line 431 of file pytypes.h.

Referenced by ~error_already_set().

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/pybind11.h
python/pybind11/include/pybind11/pybind11.h

Public Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ error_already_set() [1/4]

◆ error_already_set() [2/4]

◆ error_already_set() [3/4]

◆ ~error_already_set()

◆ error_already_set() [4/4]

Member Function Documentation

◆ clear() [1/2]

◆ clear() [2/2]

◆ discard_as_unraisable() [1/4]

◆ discard_as_unraisable() [2/4]

◆ discard_as_unraisable() [3/4]

◆ discard_as_unraisable() [4/4]

◆ m_fetched_error_deleter()

◆ matches() [1/2]

◆ matches() [2/2]

◆ restore() [1/2]

◆ restore() [2/2]

◆ trace() [1/2]

◆ trace() [2/2]

◆ type() [1/2]

◆ type() [2/2]

◆ value() [1/2]

◆ value() [2/2]

◆ what()

Member Data Documentation

◆ m_fetched_error

◆ m_trace

◆ m_type

◆ m_value