The PyQt4 Extension API — PyQt 4.12 Reference Guide

# The PyQt4 Extension API

New in version 4.12.

An important feature of PyQt4 (and SIP generated modules in general) is the ability for other extension modules to build on top of it. QScintilla is such an example.

PyQt4 provides an extension API that can be used by other modules. This has the advantage of sharing code and also enforcing consistent behaviour. Part of the API is accessable from Python and part from C++.

## Python API

The Python part of the API is accessible via the `QtCore` module and is typically used by an extension module’s equivalent of PyQt4’s configure.py.

The API consists of `PyQt4.QtCore.PYQT_CONFIGURATION` which is a dict that describes how PyQt4 was configured. At the moment it contains a single value called `sip_flags` which is a string containing the `-t` and `-x` flags that were passed to the sip executable by configure.py. Other extension modules must use the same flags in their configuration.

This information is also provided by SIP v4’s `sipconfig` module. However this module will not be implemented by SIP v5.

## C++ API

The C++ API is a set of functions. The addresses of each function is obtained by calling SIP’s `sipImportSymbol()` function with the name of the function required.

Several of the functions are provided as a replacement for SIP v4 features (i.e. `SIP_ANYSLOT`, `SIP_QOBJECT`, `SIP_RXOBJ_CON`, `SIP_RXOBJ_DIS`, `SIP_SIGNAL`, `SIP_SLOT`, `SIP_SLOT_CON` and `SIP_SLOT_DIS`) that are not supported by SIP v5.

The functions exported by PyQt4 are as follows:

char **```pyqt4_from_argv_list`(PyObject *argv_list, int &argc)

  Convert a Python list to a standard C array of command line arguments and an argument count.

  Parameters: | argv_list – is the Python list of arguments. argc – is updated with the number of arguments in the list.
  Returns: | an array of pointers to the arguments on the heap.

PyObject *```pyqt4_from_qvariant_by_type`(QVariant &value, PyObject *type)

  Convert a `QVariant` to a Python object according to an optional Python type.

  Parameters: | value – is the value to convert. type – is the Python type.
  Returns: | the converted value. If it is `0` then a Python exception will have been raised.

sipErrorState ```pyqt4_get_connection_parts`(PyObject *slot, QObject *transmitter, const char *signal_signature, bool single_shot, QObject **receiver, QByteArray &slot_signature)

  Get the receiver object and slot signature to allow a signal to be connected to an optional transmitter.

  Parameters: | slot – is the slot and should be a callable or a bound signal. transmitter – is the optional `QObject` transmitter. signal_signature – is the signature of the signal to be connected. single_shot – is `true` if the signal will only ever be emitted once. receiver – is updated with the `QObject` receiver. This may be a proxy if the slot requires it. slot_signature – is updated with the signature of the slot.
  Returns: | the error state. If this is `sipErrorFail` then a Python exception will have been raised.

const char *```pyqt4_get_pyqtsignal_parts`(PyObject *signal, QObject **transmitter)

  Get the signal signature (and, optionally, the transmitter object) from a signal.

  Parameters: | signal – is the signal. transmitter – if it is a non-zero value it is updated with the `QObject` transmitter.
  Returns: | the signature of the signal. This will be zero if the signal not a bound signal (if the transmitter was requested) or an unbound signal.

sipErrorState ```pyqt4_get_pyqtslot_parts`(PyObject *slot, QObject **receiver, QByteArray &slot_signature)

  Get the receiver object and slot signature from a callable decorated with `pyqtSlot()`.

  Parameters: | slot – is the callable slot. receiver – is updated with the `QObject` receiver. slot_signature – is updated with the signature of the slot.
  Returns: | the error state. If this is `sipErrorFail` then a Python exception will have been raised.

const char *```pyqt4_get_signal`(PyObject *signal)

  Check that a Python object was returned by `SIGNAL()` or a signal object and return the string.

  Parameters: | signal – is the signal.
  Returns: | the string. It will be 0 if the object does not refer to a signal.

const char *```pyqt4_get_slot`(PyObject *slot)

  Check that a Python object was returned by `SLOT()` or `SIGNAL()` and return the string.

  Parameters: | slot – is the slot.
  Returns: | the slot. It will be 0 if the object does not refer to a slot.

void ```pyqt4_register_from_qvariant_convertor`(bool (*convertor)(const QVariant *, PyObject **))

  Register a convertor function that converts a `QVariant` value to a Python object.

  Parameters: | convertor – is the convertor function. This takes two arguments. The first argument is the `QVariant` value to be converted. The second argument is updated with a reference to the result of the conversion and it will be `0`, and a Python exception raised, if there was an error. The convertor will return `true` if the value was handled so that no other convertor will be tried.

void ```pyqt4_register_to_qvariant_convertor`(bool (*convertor)(PyObject *, QVariant *, bool *))

  Register a convertor function that converts a Python object to a `QVariant` value.

  Parameters: | convertor – is the convertor function. This takes three arguments. The first argument is the Python object to be converted. The second argument is a pointer to `QVariant` value that is updated with the result of the conversion. The third argument is updated with an error flag which will be `false`, and a Python exception raised, if there was an error. The convertor will return `true` if the value was handled so that no other convertor will be tried.

void ```pyqt4_register_to_qvariant_data_convertor`(bool (*convertor)(PyObject *, void *, int, bool *))

  Register a convertor function that converts a Python object to the pre-allocated data of a `QVariant` value.

  Parameters: | convertor – is the convertor function. This takes four arguments. The first argument is the Python object to be converted. The second argument is a pointer to the pre-allocated data of a `QVariant` value that is updated with the result of the conversion. The third argument is the meta-type of the value. The fourth argument is updated with an error flag which will be `false`, and a Python exception raised, if there was an error. The convertor will return `true` if the value was handled so that no other convertor will be tried.

void ```pyqt4_update_argv_list`(PyObject *argv_list, int argc, char **argv)

  Update a Python list from a standard C array of command line arguments and an argument count. This is used in conjunction with `pyqt4_from_argv_list()` to handle the updating of argument lists after calling constructors of classes such as `QCoreApplication`.

  Parameters: | argv_list – is the Python list of arguments that will be updated. argc – is the number of command line arguments. argv – is the array of pointers to the arguments on the heap.