How to raise Python exception from a C extension?

When writing a C extension for Python, you might need to raise an exception if something goes wrong in your C code. Python provides a special C API that helps you to raise errors in a way that works just like regular Python exceptions.

This is helpful because even if your code is written in C for better performance, users can still handle errors using Python's normal try...except blocks. It makes your extension feel just like any other Python module.

Using Python C API to Raise Exceptions

In C extensions for Python, you can raise exceptions using the Python C API functions like PyErr_SetString() or PyErr_SetObject(). These functions don't stop the C code right away, they just tell Python that an error has happened.

To actually raise the exception in Python, your C function must return NULL. This signals the Python interpreter that an error occurred, and it will then handle the exception as if it was raised in normal Python code.

Basic Exception Raising Example

The following C extension code defines a function that raises a ValueError if the input number is negative ?

#include <Python.h>

static PyObject* check_positive(PyObject* self, PyObject* args) {
    int num;
    if (!PyArg_ParseTuple(args, "i", &num))
        return NULL;

    if (num < 0) {
        PyErr_SetString(PyExc_ValueError, "Negative value not allowed");
        return NULL;
    }

    return PyLong_FromLong(num);
}

static PyMethodDef MyMethods[] = {
    {"check_positive", check_positive, METH_VARARGS, "Checks if a number is positive"},
    {NULL, NULL, 0, NULL}
};

static struct PyModuleDef mymodule = {
    PyModuleDef_HEAD_INIT,
    "myextension",   /* name of module */
    NULL,            /* module documentation */
    -1,              /* size of per-interpreter state of the module */
    MyMethods
};

PyMODINIT_FUNC PyInit_myextension(void) {
    return PyModule_Create(&mymodule);
}

After compiling the extension, you can use it in Python like this ?

import myextension

myextension.check_positive(10)   # Returns 10
myextension.check_positive(-5)   # Raises ValueError

We get the following error for the second call ?

ValueError: Negative value not allowed

This shows how you can raise a Python exception from C and handle it just like any normal Python error.

Raising Different Types of Exceptions

You can raise any built-in exception from your Python C extension using the appropriate exception object. Python provides many built-in types like PyExc_TypeError, PyExc_ValueError, PyExc_IndexError, PyExc_IOError, etc., which can be used to indicate specific error conditions.

TypeError Example

This C function raises a TypeError when the input is not a string ?

#include <Python.h>

static PyObject* expect_string(PyObject* self, PyObject* args) {
    const char* text;
    if (!PyArg_ParseTuple(args, "s", &text)) {
        PyErr_SetString(PyExc_TypeError, "Expected a string");
        return NULL;
    }
    return PyUnicode_FromString(text);
}

Compilation Setup

Save the C code in a file named myextension.c. Then create a setup.py file to build it ?

from setuptools import setup, Extension

module = Extension("myextension", sources=["myextension.c"])

setup(
    name="myextension",
    version="1.0",
    description="A simple C extension that expects a string",
    ext_modules=[module]
)

In the terminal, run the following command to build the extension ?

python3 setup.py build_ext --inplace

Handling Exceptions in Python Code

After raising exceptions from C, you can catch them using standard Python error handling with try...except blocks. This makes the user experience smooth even when the logic is implemented in C.

Example Usage

The following Python code shows how to handle exceptions raised from C extensions ?

import myextension

# Handle ValueError
try:
    result = myextension.check_positive(-3)
except ValueError as e:
    print("Caught from C extension:", e)

# Handle TypeError  
try:
    result = myextension.expect_string(123)
except TypeError as e:
    print("Type error:", e)

Caught from C extension: Negative value not allowed
Type error: Expected a string

Using Custom Exceptions

You can define and raise your own custom exception classes directly from your C extension. First, define a custom exception object during module initialization ?

static PyObject* MyCustomError;

PyMODINIT_FUNC PyInit_myextension(void) {
    PyObject* m = PyModule_Create(&mymodule);
    if (m == NULL)
        return NULL;

    MyCustomError = PyErr_NewException("myextension.MyCustomError", NULL, NULL);
    Py_XINCREF(MyCustomError);
    PyModule_AddObject(m, "MyCustomError", MyCustomError);
    return m;
}

Once registered, you can raise it in any function ?

if (some_error_condition) {
    PyErr_SetString(MyCustomError, "Something went wrong!");
    return NULL;
}

Catching Custom Exceptions

From Python, you can catch the custom exception using try...except blocks ?

try:
    myextension.some_function()
except myextension.MyCustomError as e:
    print("Caught custom error:", e)

Conclusion

Raising Python exceptions from C extensions is achieved using PyErr_SetString() and returning NULL. This allows seamless integration with Python's exception handling, making C extensions behave like native Python modules.