C APIs for Handwritten Code

The sip module implements 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. Semantic versioning is used so that, for example, v13.1 is compatible with v13.0 but is incompatible with v12.0, v13.2 and v14.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 API are described in subsequent sections. The remainder of this section covers topics that are common to all API versions.

Generated Type Specifications

SIP generates an opaque type specification for each C structure, C++ class, C++ namespace, named enum or mapped type being wrapped which are used extensively by an API. The C type of a specification is specific to the ABI version.

The names of these specifications have a sipType_ prefix.

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

For those specifications 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 specification of a mapped type is to use sipFindType().

The type specifications 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.

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. Event handlers are registered using sipRegisterEventHandlers() or sipRegisterEventHandler(). The signature of an event handler is specific to the event type.

Using the C API when Embedding

Note

ABI v14 does not currently support 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 specifications that SIP generates for a wrapped module 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.