Initial import of SIP4 for Qt3

1 files changed, 282 insertions, 0 deletions

diff --git a/sphinx/python_api.rst b/sphinx/python_api.rst
new file mode 100644
index 0000000..fa90411
--- /dev/null
+++ b/sphinx/python_api.rst
@@ -0,0 +1,282 @@
+.. _ref-python-api:
+
+Python API for Applications
+===========================
+
+.. module:: sip
+
+The main purpose of the :mod:`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.
+
+
+.. function:: cast(obj, type) -> object
+
+    This does the Python equivalent of casting a C++ instance to one of its
+    sub or super-class types.
+
+    :param obj:
+        the Python object.
+    :param type:
+        the type.
+    :return:
+        a new Python object is that wraps the same C++ instance as *obj*, but
+        has the type *type*.
+
+
+.. function:: delete(obj)
+
+    For C++ instances this calls the C++ destructor.  For C structures it
+    returns the structure's memory to the heap.
+
+    :param obj:
+        the Python object.
+
+
+.. function:: 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.
+
+    :param obj:
+        the Python object.
+
+
+.. function:: getapi(name) -> version
+
+    .. versionadded:: 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 :func:`sip.setapi` or
+    implicitly by importing the module that defines it.
+
+    :param name:
+        the name of the API.
+    :return:
+        The version number that has been set for the API.  An exception will
+        be raised if the API is unknown.
+
+
+.. function:: isdeleted(obj) -> bool
+
+    This checks if the C++ instance or C structure has been deleted and
+    returned to the heap.
+
+    :param obj:
+        the Python object.
+    :return:
+        ``True`` if the C/C++ instance has been deleted.
+
+
+.. function:: ispyowned(obj) -> bool
+
+    This checks if the C++ instance or C structure is owned by Python.
+
+    :param obj:
+        the Python object.
+    :return:
+        ``True`` if the C/C++ instance is owned by Python.
+
+
+.. function:: setapi(name, version)
+
+    .. versionadded:: 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.
+
+    :param name:
+        the name of the API.
+    :param version:
+        The version number to set for the API.  Version numbers must be
+        greater than or equal to 1.
+
+
+.. function:: 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.
+
+    :param obj:
+        the Python object.
+
+
+.. function:: settracemask(mask)
+
+    If the bindings have been created with SIP's :option:`-r <sip -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.)
+
+    :param 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.
+
+
+.. data:: SIP_VERSION
+
+    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``).
+    It was first implemented in SIP v4.2.
+
+
+.. data:: SIP_VERSION_STR
+
+    This is a Python string object that defines the SIP version number as
+    represented as a string.  For development snapshots it will start with
+    ``snapshot-``.  It was first implemented in SIP v4.3.
+
+
+.. function:: transferback(obj)
+
+    This function is a wrapper around :cfunc:`sipTransferBack()`.
+
+
+.. function:: transferto(obj, owner)
+
+    This function is a wrapper around :cfunc:`sipTransferTo()`.
+
+
+.. function:: unwrapinstance(obj) -> integer
+
+    This returns the address, as an integer, of a wrapped C/C++ structure or
+    class instance.
+
+    :param obj:
+        the Python object.
+    :return:
+        an integer that is the address of the C/C++ instance.
+
+
+.. class:: 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 protocol is supported.  This means that the memory can
+    be treated as a mutable array of bytes when wrapped with the ``buffer()``
+    builtin.  The type has the following methods.
+
+    .. method:: __init__(address[, size=-1[, writeable=True]])
+
+        :param address:
+            the address, either another :class:`sip.voidptr`, ``None``, a
+            Python Capsule, a Python CObject, or an integer.
+        :param size:
+            the optional associated size of the block of memory and is negative
+            if the size is not known.
+        :param writeable:
+            set if the memory is writeable.  If it is not specified, and
+            *address* is a :class:`sip.voidptr` instance then its value will be
+            used.
+
+    .. method:: __int__() -> integer
+
+        This returns the address as an integer.
+
+        :return:
+            the integer address.
+
+    .. method:: __hex__() -> string
+
+        This returns the address as a hexadecimal string.
+
+        :return:
+            the hexadecimal string address.
+
+    .. method:: ascapsule() -> capsule
+
+        .. versionadded:: 4.10
+
+        This returns the address as an unnamed Python Capsule.  This requires
+        Python v3.1 or later or Python v2.7 or later.
+
+        :return:
+            the Capsule.
+
+    .. method:: ascobject() -> cObject
+
+        This returns the address as a Python CObject.  This is deprecated with
+        Python v3.1 or later.
+
+        :return:
+            the CObject.
+
+    .. method:: 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.
+        
+        :param 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.
+        :return:
+            the string or bytes object.
+
+    .. method:: getsize() -> integer
+
+        This returns the size associated with the address.
+        
+        :return:
+            the associated size which will be negative if there is none.
+
+    .. method:: setsize(size)
+
+        This sets the size associated with the address.
+        
+        :param size:
+            the size to associate.  If it is negative then no size is
+            associated.
+
+    .. method:: getwriteable() -> bool
+
+        This returns the writeable state of the memory.
+
+        :return:
+            ``True`` if the memory is writeable.
+
+    .. method:: setwriteable(writeable)
+
+        This sets the writeable state of the memory.
+
+        :param writeable:
+            the writeable state to set.
+
+
+.. function:: 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.
+    
+    :param addr:
+        the address of the instance as a number.
+    :param type:
+        the Python type of the instance.
+    :return:
+        the Python object that wraps the instance.
+
+
+.. class:: wrapper
+
+    This is the type object of the base type of all instances wrapped by SIP.
+
+
+.. class:: wrappertype
+
+    This is the type object of the metatype of the :class:`sip.wrapper` type.