Python API for Applications — SIP v4.19.25 Reference Guide

# Python API for Applications

The main purpose of the `sip` module is to provide functionality common to all SIP generated bindings. It is loaded automatically and most of the time you will completely ignore it. However, it does expose some functionality that can be used by applications.

New in version 4.19.4.

When a private copy of the SIP module is being used it would normally be imported from the package containing the private copy. However, in order to maintain compatibility with earlier versions, the module can also be imported as a top-level module so long as a SIP-generated extension module has previously been imported.

class `sip.` `array`

  New in version 4.15.

  This is the type object for the type SIP uses to represent an array of a limited number of C/C++ types. Typically the memory is not owned by Python so that it is not freed when the object is garbage collected. A `sip.array` object can be created from a `sip.voidptr` object by calling `sip.voidptr.asarray()`. This allows the underlying memory (interpreted as a sequence of unsigned bytes) to be processed much more quickly.

`sip.` `assign`(obj, other)

  New in version 4.19.

  This does the Python equivalent of invoking the assignment operator of a C++ instance (i.e. `*obj = other`).

  Parameters

    - obj – the Python object being assigned to.

    - other – the Python object being assigned.

`sip.` `cast`(obj, type) → object

  This does the Python equivalent of casting a C++ instance to one of its sub or super-class types.

  Parameters

    - obj – the Python object.

    - type – the type.

  Returns

    a new Python object is that wraps the same C++ instance as obj, but has the type type.

`sip.` `delete`(obj)

  For C++ instances this calls the C++ destructor. For C structures it returns the structure’s memory to the heap.

  Parameters

    obj – the Python object.

`sip.` `dump`(obj)

  This displays various bits of useful information about the internal state of the Python object that wraps a C++ instance or C structure. Note that the reference count that is displayed has the same caveat as that of `sys.getrefcount()`.

  Parameters

    obj – the Python object.

`sip.` `enableautoconversion`(type, enable) → bool

  New in version 4.14.7.

  Instances of some classes may be automatically converted to other Python objects even though the class has been wrapped. This allows that behaviour to be suppressed so that an instances of the wrapped class is returned instead. By default it is enabled.

  Parameters

    - type – the Python type object.

    - enable – is `True` if auto-conversion should be enabled for the type.

  Returns

    `True` or `False` depending on whether or not auto-conversion was previously enabled for the type. This allows the previous state to be restored later on.

`sip.` `enableoverflowchecking`(enable) → bool

  New in version 4.19.4.

  This enables or disables the checking for overflows when converting Python integer objects to C/C++ integer types. When it is enabled an exception is raised when the value of a Python integer object is too large to fit in the corresponding C/C++ type. By default it is disabled.

  Parameters

    enable – is `True` if overflow checking should be enabled.

  Returns

    `True` or `False` depending on whether or not overflow checking was previously enabled. This allows the previous state to be restored later on.

`sip.` `getapi`(name) → version

  New in version 4.9.

  This returns the version number that has been set for an API. The version number is either set explicitly by a call to `sip.setapi()` or implicitly by importing the module that defines it.

  Parameters

    name – the name of the API.

  Returns

    The version number that has been set for the API. An exception will be raised if the API is unknown.

`sip.` `isdeleted`(obj) → bool

  This checks if the C++ instance or C structure has been deleted and returned to the heap.

  Parameters

    obj – the Python object.

  Returns

    `True` if the C/C++ instance has been deleted.

`sip.` `ispycreated`(obj) → bool

  New in version 4.12.1.

  This checks if the C++ instance or C structure was created by Python. If it was then it is possible to call a C++ instance’s protected methods.

  Parameters

    obj – the Python object.

  Returns

    `True` if the C/C++ instance was created by Python.

`sip.` `ispyowned`(obj) → bool

  This checks if the C++ instance or C structure is owned by Python.

  Parameters

    obj – the Python object.

  Returns

    `True` if the C/C++ instance is owned by Python.

`sip.` `setapi`(name, version)

  New in version 4.9.

  This sets the version number of an API. An exception is raised if a different version number has already been set, either explicitly by a previous call, or implicitly by importing the module that defines it.

  Parameters

    - name – the name of the API.

    - version – The version number to set for the API. Version numbers must be greater than or equal to 1.

`sip.` `setdeleted`(obj)

  This marks the C++ instance or C structure as having been deleted and returned to the heap so that future references to it raise an exception rather than cause a program crash. Normally SIP handles such things automatically, but there may be circumstances where this isn’t possible.

  Parameters

    obj – the Python object.

`sip.` `setdestroyonexit`(destroy)

  New in version 4.14.2.

  When the Python interpreter exits it garbage collects those objects that it can. This means that any corresponding C++ instances and C structures owned by Python are destroyed. Unfortunately this happens in an unpredictable order and so can cause memory faults within the wrapped library. Calling this function with a value of `False` disables the automatic destruction of C++ instances and C structures.

  Parameters

    destroy – `True` if all C++ instances and C structures owned by Python should be destroyed when the interpreter exits. This is the default.

`sip.` `settracemask`(mask)

  If the bindings have been created with SIP’s `-r` command line option then the generated code will include debugging statements that trace the execution of the code. (It is particularly useful when trying to understand the operation of a C++ library’s virtual function calls.)

  Parameters

    mask – the mask that determines which debugging statements are enabled.

  Debugging statements are generated at the following points:

  - in a C++ virtual function (mask is `0x0001`)

  - in a C++ constructor (mask is `0x0002`)

  - in a C++ destructor (mask is `0x0004`)

  - in a Python type’s __init__ method (mask is `0x0008`)

  - in a Python type’s __del__ method (mask is `0x0010`)

  - in a Python type’s ordinary method (mask is `0x0020`).

  By default the trace mask is zero and all debugging statements are disabled.

class `sip.` `simplewrapper`

  This is an alternative type object than can be used as the base type of an instance wrapped by SIP. Objects using this are smaller than those that use the default `sip.wrapper` type but do not support the concept of object ownership.

`sip.` `SIP_VERSION`

  New in version 4.2.

  This is a Python integer object that represents the SIP version number as a 3 part hexadecimal number (e.g. v4.0.0 is represented as `0x040000`).

`sip.` `SIP_VERSION_STR`

  New in version 4.3.

  This is a Python string object that defines the SIP version number as represented as a string. For development versions it will contain either `.dev` or `-snapshot-`.

`sip.` `transferback`(obj)

  This function is a wrapper around `sipTransferBack()`.

`sip.` `transferto`(obj, owner)

  This function is a wrapper around `sipTransferTo()`.

`sip.` `unwrapinstance`(obj) → integer

  This returns the address, as an integer, of a wrapped C/C++ structure or class instance.

  Parameters

    obj – the Python object.

  Returns

    an integer that is the address of the C/C++ instance.

class `sip.` `voidptr`

  This is the type object for the type SIP uses to represent a C/C++ `void *`. It may have a size associated with the address in which case the Python buffer interface is supported. The type has the following methods.

  `__init__`(address[, size=-1[, writeable=True]])
    Parameters

      - address – the address, either another `sip.voidptr`, `None`, a Python Capsule, a Python CObject, an object that implements the buffer protocol or an integer.

      - size – the optional associated size of the block of memory and is negative if the size is not known.

      - writeable – set if the memory is writeable. If it is not specified, and address is a `sip.voidptr` instance then its value will be used.

  `__int__`() → integer

    This returns the address as an integer.

    Returns

      the integer address.

  `__getitem__`(idx) → item

    New in version 4.12.

    This returns the item at a given index. An exception will be raised if the address does not have an associated size. In this way it behaves like a Python `memoryview` object.

    Parameters

      idx – is the index which may either be an integer, an object that implements `__index__()` or a slice object.

    Returns

      the item. If the index is an integer then the item will be a Python v2 string object or a Python v3 bytes object containing the single byte at that index. If the index is a slice object then the item will be a new `voidptr` object defining the subset of the memory corresponding to the slice.

  `__hex__`() → string

    This returns the address as a hexadecimal string.

    Returns

      the hexadecimal string address.

  `__len__`() → integer

    New in version 4.12.

    This returns the size associated with the address.

    Returns

      the associated size. An exception will be raised if there is none.

  `__setitem__`(idx, item)

    New in version 4.12.

    This updates the memory at a given index. An exception will be raised if the address does not have an associated size or is not writable. In this way it behaves like a Python `memoryview` object.

    Parameters

      - idx – is the index which may either be an integer, an object that implements `__index__()` or a slice object.

      - item – is the data that will update the memory defined by the index. It must implement the buffer interface and be the same size as the data that is being updated.

  `asarray`([size=-1]) → :class:`sip.array`

    New in version 4.16.5.

    This returned the block of memory as a `sip.array` object. The memory is not copied.

    Parameters

      size – the size of the array. If it is negative then the size associated with the address is used. If there is no associated size then an exception is raised.

    Returns

      the `sip.array` object.

  `ascapsule`() → capsule

    New in version 4.10.

    This returns the address as an unnamed Python Capsule. This requires Python v3.1 or later or Python v2.7 or later.

    Returns

      the Capsule.

  `ascobject`() → cObject

    This returns the address as a Python CObject. This is deprecated with Python v3.1 and is not supported with Python v3.2 and later.

    Returns

      the CObject.

  `asstring`([size=-1]) → string/bytes

    This returns a copy of the block of memory as a Python v2 string object or a Python v3 bytes object.

    Parameters

      size – the number of bytes to copy. If it is negative then the size associated with the address is used. If there is no associated size then an exception is raised.

    Returns

      the string or bytes object.

  `getsize`() → integer

    This returns the size associated with the address.

    Returns

      the associated size which will be negative if there is none.

  `setsize`(size)

    This sets the size associated with the address.

    Parameters

      size – the size to associate. If it is negative then no size is associated.

  `getwriteable`() → bool

    This returns the writeable state of the memory.

    Returns

      `True` if the memory is writeable.

  `setwriteable`(writeable)

    This sets the writeable state of the memory.

    Parameters

      writeable – the writeable state to set.

`sip.` `wrapinstance`(addr, type) → object

  This wraps a C structure or C++ class instance in a Python object. If the instance has already been wrapped then a new reference to the existing object is returned.

  Parameters

    - addr – the address of the instance as a number.

    - type – the Python type of the instance.

  Returns

    the Python object that wraps the instance.

class `sip.` `wrapper`

  This is the type object of the default base type of all instances wrapped by SIP. The `Supertype` class annotation can be used to specify a different base type for a class.

class `sip.` `wrappertype`

  This is the type object of the metatype of the `sip.wrapper` type.