Python Exceptions

Detailed Description

Handling Python exceptions in C++, and translating C++ exceptions to Python.

This module provides utilities for converting C++ exceptions into Python exceptions, and for handling Python exceptions in C++ code.

Its main part is the class PythonException that represents a Python exception in C++ code. Additionally, it provides functions and macros to facilitate raising and handling Python exceptions.

Data Structures
class	lass::python::PythonException
	C++ exception type that holds a Python exception. More...
struct	lass::python::impl::PythonFetchRaiser
	Raiser type for enforcers that raises a Python exception. More...

Macros
#define	PY_ENFORCE_POINTER(pointer)
	Enforce that a Python pointer is not null.
#define	PY_ENFORCE_ZERO(expression)
	Enforce that an expression evaluates to zero.
#define	PY_ENFORCE_NOTZERO(expression)
	Enforce that an expression evaluates to not zero.

Functions
PyObject *	lass::python::chainErrFormat (PyObject *exception, const char *format,...)
	Raise an explicitly chained Python exception.
PyObject *	lass::python::chainErrFormatV (PyObject *exception, const char *format, va_list vargs)
	Raise an explicitly chained Python exception.
void	lass::python::impl::addMessageHeader (const char *header)
	Prepend a message to the current Python exception value.
void	lass::python::impl::fetchAndThrowPythonException (std::string loc="")
	Fetch the current Python exception and throw it as a C++ PythonException.
void	lass::python::impl::handleException (std::exception_ptr error)
	Handle a C++ exception by raising an Python exception.

Macro Definition Documentation

PY_ENFORCE_POINTER

#define PY_ENFORCE_POINTER

(

pointer

)

Value:

        *LASS_UTIL_IMPL_MAKE_ENFORCER(\
        ::lass::util::impl::TruePredicate,\
        ::lass::python::impl::PythonFetchRaiser,\
        (pointer), \
        int(0), \
        "'" LASS_STRINGIFY(pointer) "' in " LASS_HERE)

Enforce that a Python pointer is not null.

Exceptions

lass::python::PythonException

See also

lass::python::impl::PythonFetchRaiser

Enforcers

Definition at line 236 of file python/exception.h.

Referenced by lass::python::getPyObjectByName(), lass::python::impl::makeIntFlagType(), lass::python::impl::makeStrEnumType(), and lass::python::putenv().

PY_ENFORCE_ZERO

#define PY_ENFORCE_ZERO

(

expression

)

Value:

        *LASS_UTIL_IMPL_MAKE_ENFORCER(\
        ::lass::util::impl::EqualPredicate,\
        ::lass::python::impl::PythonFetchRaiser,\
        (expression), \
        int(0), \
        "'" LASS_STRINGIFY(expression) "' in " LASS_HERE)

Enforce that an expression evaluates to zero.

Exceptions

lass::python::PythonException

See also

lass::python::impl::PythonFetchRaiser

Enforcers

Definition at line 253 of file python/exception.h.

Referenced by lass::python::putenv().

PY_ENFORCE_NOTZERO

#define PY_ENFORCE_NOTZERO

(

expression

)

Value:

        *LASS_UTIL_IMPL_MAKE_ENFORCER(\
        ::lass::util::impl::UnequalPredicate,\
        ::lass::python::impl::PythonFetchRaiser,\
        (expression), \
        int(0), \
        "'" LASS_STRINGIFY(expression) "' in " LASS_HERE)

Enforce that an expression evaluates to not zero.

Exceptions

lass::python::PythonException

See also

lass::python::impl::PythonFetchRaiser

Enforcers

Definition at line 270 of file python/exception.h.

Function Documentation

chainErrFormat()

LASS_PYTHON_DLL PyObject *LASS_CALL lass::python::chainErrFormat	(	PyObject *	exception,
		const char *	format,
			... )

Raise an explicitly chained Python exception.

Like PyErr_Format, but chains the new exception to the current one if any is set. More explicitly, if a Python exception is already set, that is if PyErr_Occurred() returns true, then the current exception is fetched and used as the __cause__ and __context__ of the new exception.

Roughly equivalent to:

except Exception as err:
   raise exception(format % vargs) from err

For more information on exception chaining, see: https://docs.python.org/3/library/exceptions.html#exception-context

If no exception is currently set, this function behaves like PyErr_Format.

Parameters

exception	The Python exception type to raise, e.g. PyExc_TypeError.
format,...	The format string and arguments, like in PyErr_Format. They do not behave like printf, but they have the same meaning as in PyUnicode_FromFormat.

Returns

Always returns nullptr, so that it can be used directly in return statements.

Definition at line 296 of file python/exception.cpp.

References chainErrFormatV().

Referenced by lass::python::ModuleDefinition::inject().

chainErrFormatV()

LASS_PYTHON_DLL PyObject *LASS_CALL lass::python::chainErrFormatV	(	PyObject *	exception,
		const char *	format,
		va_list	vargs )

Raise an explicitly chained Python exception.

Like chainErrFormat(), but takes a va_list instead of variable arguments.

Definition at line 307 of file python/exception.cpp.

Referenced by chainErrFormat().

addMessageHeader()

LASS_PYTHON_DLL void LASS_CALL lass::python::impl::addMessageHeader

(

const char *

header

)

Prepend a message to the current Python exception value.

This function adds a custom header to the current Python exception message, if one is set. This can be useful for providing additional context about the error.

If no exception is currently set, i.e. PyErr_Occurred() returns false, then this function does nothing.

Parameters

header

The header to add to the exception message.

Note

Only works for exceptions whose value is a string. If the value is not a string, the function does nothing.

Definition at line 123 of file python/exception.cpp.

handleException()

LASS_PYTHON_DLL void LASS_CALL lass::python::impl::handleException

(

std::exception_ptr

error

)

Handle a C++ exception by raising an Python exception.

This function translates a C++ exception into a Python exception. It supports PythonException, util::Exception, and standard C++ exceptions. It also supports std::filesystem::filesystem_error and std::system_error by translating the error code to an appropriate OSError subclass.

If the exception type is not recognized, it will be translated to a generic Exception with the what() message of the C++ exception.

Parameters

error

The exception pointer to handle. This is typically obtained using std::current_exception().

Definition at line 171 of file python/exception.cpp.

References lass::python::fromSharedPtrToNakedCast().