ABI Versions

Note

ABI v14 is currently considered to be experimental. It will continue to be developed and refined and its full version number will remain at v14.0.0 during this process.

SIP implements a set of ABIs which have slightly different behaviours and are used by the generated extension modules of package projects to allow them to interact. A bindings author must choose which ABI version they are going to target. Extension modules that are part of the same package must target the same ABI version.

Each ABI has a corresponding C API that is used by bindings authors in handwritten code.

ABI v14 Features

This ABI is intended to replace the older ABIs. Existing projects that use an older ABI should plan to migrate to this ABI. However bindings authors should be aware that their bindings may behave in slightly different ways which should be communicated to their users. (These changes are enhancements and, arguably, bug fixes.)

  • Python v3.15 or later is required.

  • C++20 support is required when wrapping C++ libraries.

  • Multiple interpreters are supported.

  • Free-threading (i.e. no-GIL) is supported.

  • Extension modules can be unimported and reimported (assuming the library being wrapped allows this).

  • The implementation of enums can be configured to match the behavior of either v12 or v13.

  • The naming of sip module types can be configured to match the behaviour of v12.

  • The behaviour when setting the value of wrapped static variables (of either modules or classes) has changed. With ABI v14 the value of the variable is changed appropriately and may involve a type conversion of the new value (if the new value has a different type to the C/C++ variable). With older ABIs the Python attribute would be changed to the new value but the underlying C/C++ variable would not be change. This change also means that const global variables can no longer be modified.

  • The legacy pickle format is not supported. Applications need to rewrite any pickled data using ABI v12.19 (or later) or ABI v13.12 (or later) before using ABI v14.

  • Any wrapped type can now be used as a mixin and there is no need to identify mixin classes using the Mixin class annotation.

  • The cast() function of the sip module is not supported.

  • The %GetCode and %SetCode directives can now also be used for global variables.

  • The support for namespaces defined across modules is now complete. For example if a function is defined in a namespace in one module it is now possible to define a new overload in another module so that it is visible as such in the original module.

  • The DisallowNone argument annotation is now supported for string and array types, capsules, structs, unions and void pointers.

  • Inplace operators now return a value with the type specified as the return type in the .sip file. Older ABIs assumed that such operators returned self and ignored the return type in the .sip file. This means that the reference to the wrapped object is correctly rebound to the object returned by the operator. For example, an operator declared as void operator+=(int) and called as klass += 5 will result in klass having a value of None as it has been rebound to the value returned by the operator (ie. None). This behaviour is consistent with that of a Python implementation of __iadd__().

The internal design of this ABI means that significant new features can be added without affecting binary compatibility. Therefore a newer ABI should only be needed if new versions of Python itself imposes major changes (as it did to support free-threading).

ABI v13 Features

This ABI was introduced primarily to make the handling of enums consistent once the enum module had been added to Python’s standard library.

  • C++11 support is required when wrapping C++ libraries.

  • All enums are implemented using the standard Enum and related Python types.

This ABI will be supported until October 2030 (when Python v3.14 is no longer supported).

ABI v12 Features

This is the oldest ABI that is still supported.

  • Traditional enums are implemented as a custom Python type.

  • C++ scoped enums are implemented using the standard Enum Python type.

  • The module part of the fully qualified name of sip module types (e.g. sip.simplewrapper) is always just sip even if the module is part of a package. (Note that this is a bug that won’t be fixed because user applications may depend on it.)

This ABI will be supported until October 2030 (when Python v3.14 is no longer supported).