C API for Handwritten Code

The sip module provides an API that can be used by handwritten code in specification files. The API has a number of versions each of which is implemented by an ABI. ABIs use semantic versionion so that, for example, v12.1 is compatible with v12.0 but is incompatible with v11.0, v12.2 and v13.0.

The API is declared in the sip.h header file. SIP will ensure this file is installed in a location such that the compiler will automatically find it.

The details of each currently supported ABI are described in subsequent sections. The remainder of this section covers topics that are common to all ABI versions.

Generated Type Structures

SIP generates an opaque type structure for each C structure, C++ class, C++ namespace, traditional named enum or mapped type being wrapped. These are sipTypeDef structures and are used extensively by the API.

The names of these structure are prefixed by sipType_.

For those structures that correspond to C structures, C++ classes, C++ namespaces or traditional named enums the remaining part of the name is the fully qualified name of the structure, class, namespace or enum name. Any :: scope separators are replaced by an underscore. For example, the type object for class Klass is sipType_Klass.

For those structure that correspond to mapped types the remaining part of the name is generated by SIP. The only way for handwritten code to obtain a pointer to a structure for a mapped type is to use sipFindType().

The type structures of all imported types explicitly used by a module are available to handwritten code.

Generated Derived Classes

For most C++ classes being wrapped SIP generates a derived class with the same name prefixed by sip. For example, the derived class for class Klass is sipKlass.

If a C++ class doesn’t have any virtual or protected methods in it or any of it’s super-class hierarchy then a derived class is not generated.

Most of the time handwritten code should ignore the derived classes. The only exception is that handwritten constructor code specified using the %MethodCode directive should call the derived class’s constructor (which has the same C++ signature) rather then the wrapped class’s constructor.

Generated Exception Objects

SIP generates a Python object for each exception defined with the %Exception directive.

These objects are named with the fully qualified exception name (i.e. including any enclosing scope) prefixed by sipException_. For example, the type object for exception Except defined in class Klass is sipException_Klass_Except.

The objects of all imported exceptions are available to handwritten code.

Event Handlers

The sip module will trigger a number of events. Handwritten code can supply handlers for these events to allow it to perform additional actions. Each event has a type, described by the sipEventType enum. An event handler is registered using sipRegisterEventHandler(). The signature of an event handler is specific to the event type.

Using the C API when Embedding

The C API is intended to be called from handwritten code in SIP generated modules. However it is also often necessary to call it from C/C++ applications that embed the Python interpreter and need to pass C/C++ instances between the application and the interpreter.

The API is exported by the sip module as a sipAPIDef data structure (defined in the sip.h header file) containing a set of function pointers. The data structure is wrapped as a Python PyCapsule object. It is referenced by the name _C_API in the sip module’s dictionary.

Each member of the data structure is a pointer to one of the functions of the C API. The name of the member can be derived from the function name by replacing the sip prefix with api and converting each word in the name to lower case and preceding it with an underscore. For example:

sipExportSymbol becomes api_export_symbol

sipWrapperCheck becomes api_wrapper_check

Note that the type objects that SIP generates for a wrapped module (see Generated Type Structures and Generated Exception Objects) cannot be refered to directly and must be obtained using the sipFindType() function. Of course, the corresponding modules must already have been imported into the interpreter.

The following code fragment shows how to get a pointer to the sipAPIDef data structure:

#include "sip.h"

const sipAPIDef *get_sip_api()
{
    return (const sipAPIDef *)PyCapsule_Import("sip._C_API", 0);
}

"sip._C_API" should be replaced by the fully qualified name of the sip module.

If you need to install a local copy of the sip.h header file then you can do so with sip-module.