Using the C API: Assorted topics — Python 3.16.0a2 documentation
Navigation index modules | next | previous | Python » 3.16.0a2 documentation » Extending and Embedding the Python Interpreter » Using the C API: Assorted topics | Theme | Using the C API: Assorted topics ¶ The tutorial walked you through creating a C API extension module, but left many areas unexplained. This document looks at several concepts that you’ll need to learn in order to write more complex extensions. Errors and Exceptions ¶ An important convention throughout the Python interpreter is the following: when a function fails, it should set an exception condition and return an error value (usually -1 or a NULL pointer).
Exception information is stored in three members of the interpreter’s thread state. These are NULL if there is no exception. Otherwise they are the C equivalents of the members of the Python tuple returned by sys.exc_info() . These are the exception type, exception instance, and a traceback object. It is important to know about them to understand how errors are passed around. The Python API defines a number of functions to set various types of exceptions.
The most common one is PyErr_SetString() . Its arguments are an exception object and a C string. The exception object is usually a predefined object like PyExc_ZeroDivisionError . The C string indicates the cause of the error and is converted to a Python string object and stored as the “associated value” of the exception. Another useful function is PyErr_SetFromErrno() , which only takes an exception argument and constructs the associated value by inspection of the global variable errno .
The most general function is PyErr_SetObject() , which takes two object arguments, the exception and its associated value. You don’t need to Py_INCREF() the objects passed to any of these functions. You can test non-destructively whether an exception has been set with PyErr_Occurred() . This returns the current exception object, or NULL if no exception has occurred. You normally don’t need to call PyErr_Occurred() to see whether an error occurred in a function call, since you should be able to tell from the return value.
When a function f that calls another function g detects that the latter fails, f should itself return an error value (usually NULL or -1 ). It should not call one of the PyErr_* functions — one has already been called by g . f ’s caller is then supposed to also return an error indication to its caller, again without calling PyErr_* , and so on — the most detailed cause of the error was already reported by the function that first detected it.
Once the error reaches the Python interpreter’s main loop, this aborts the currently executing Python code and tries to find an exception handler specified by the Python programmer. (There are situations where a module can actually give a more detailed error message by calling another PyErr_* function, and in such cases it is fine to do so. As a general rule, however, this is not necessary, and can cause information about the cause of the error to be lost: most operations can fail for a variety of reasons.) To ignore an exception set by a function call that failed, the exception condition must be cleared explicitly by calling PyErr_Clear() .
The only time C code should call PyErr_Clear() is if it doesn’t want to pass the error on to the interpreter but wants to handle it completely by itself (possibly by trying something else, or pretending nothing went wrong). Every failing malloc() call must be turned into an exception — the direct caller of malloc() (or realloc() ) must call PyErr_NoMemory() and return a failure indicator itself. All the object-creating functions (for example, PyLong_FromLong() ) already do this, so this note is only relevant to those who call malloc() directly.
Also note that, with the important exception of PyArg_ParseTuple() and friends, functions that return an integer status usually return a positive value or zero for success and -1 for failure, like Unix system calls. Finally, be careful to clean up garbage (by making Py_XDECREF() or Py_DECREF() calls for objects you have already created) when you return an error indicator! The choice of which exception to raise is entirely yours.
There are predeclared C objects corresponding to all built-in Python exceptions, such as PyExc_ZeroDivisionError , which you can use directly. Of course, you should choose exceptions wisely — don’t use PyExc_TypeError to mean that a file couldn’t be opened (that should probably be PyExc_OSError ). If something’s wrong with the argument list, the PyArg_ParseTuple() function usually raises PyExc_TypeError . If you have an argument whose value must be in a particular range or must satisfy other conditions, PyExc_ValueError is appropriate.
You can also define a new exception that is unique to your module. The simplest way to do this is to declare a static global object variable at the beginning of the file: static PyObject * SpamError = NULL ; and initialize it by calling PyErr_NewException() in the module’s Py_mod_exec function ( spam_module_exec() ): SpamError = PyErr_NewException ( "spam.error" , NULL , NULL ); Since SpamError is a global variable, it will be overwritten every time the module is reinitialized, when the Py_mod_exec function is called.
For now, let’s avoid the issue: we will block repeated initialization by raising an ImportError : static PyObject * SpamError = NULL ; static int spam_module_exec ( PyObject * m ) { if ( SpamError != NULL ) { PyErr_SetString ( PyExc_ImportError , "cannot initialize spam module more than once" ); return -1 ; } SpamError = PyErr_NewException ( "spam.error" , NULL , NULL ); if ( PyModule_AddObjectRef ( m , "SpamError" , SpamError ) < 0 ) { return -1 ; } return 0 ; } static PyModuleDef_Slot spam_module_slots [] = { { Py_mod_exec , spam_module_exec }, { 0 , NULL } }; static struct PyModuleDef spam_module = { . m_base = PyModuleDef_HEAD_INIT , . m_name = "spam" , . m_size = 0 , // non-negative . m_slots = spam_module_slots , }; PyMODINIT_FUNC PyInit_spam ( void ) { return PyModuleDef_Init ( & spam_module ); } Note that the Python name for the exception object is spam.error .
The PyErr_NewException() function may create a class with the base class being Exception (unless another class is passed in instead of NULL ), described in Built-in Exceptions . Note also that the SpamError variable retains a reference to the newly created exception class; this is intentional! Since the exception could be removed from the module by external code, an owned reference to the class is needed to ensure that it will not be discarded, causing SpamError to become a dangling pointer.
Should it become a dangling pointer, C code which raises the exception could cause a core dump or other unintended side effects. For now, the Py_DECREF() call to remove this reference is missing. Even when the Python interpreter shuts down, the global SpamError variable will not be garbage-collected. It will “leak”. We did, however, ensure that this will happen at most once per process. We discuss the use of PyMODINIT_FUNC as a function return type later in this sample.
The spam.error exception can be raised in your extension module using a call to PyErr_SetString() as shown below: static PyObject * spam_system ( PyObject * self , PyObject * args ) { const char * command ; int sts ; if ( ! PyArg_ParseTuple ( args , "s" , & command )) return NULL ; sts = system ( command ); if ( sts < 0 ) { PyErr_SetString ( SpamError , "System command failed" ); return NULL ; } return PyLong_FromLong ( sts ); } Embedding an extension ¶ If you want to make your module a permanent part of the Python interpreter, you will have to change the configuration setup and rebuild the interpreter.
On Unix, place your file ( spammodule.c for example) in the Modules/ directory of an unpacked source distribution, add a line to the file Modules/Setup.local describing your file: spam spammodule.o and rebuild the interpreter by
The rest of this page is on the live site.