diff options
Diffstat (limited to 'sphinx')
| -rw-r--r-- | sphinx/annotations.rst | 805 | ||||
| -rw-r--r-- | sphinx/build_system.rst | 843 | ||||
| -rw-r--r-- | sphinx/builtin.rst | 50 | ||||
| -rw-r--r-- | sphinx/c_api.rst | 1721 | ||||
| -rw-r--r-- | sphinx/command_line.rst | 137 | ||||
| -rw-r--r-- | sphinx/conf.py | 231 | ||||
| -rw-r--r-- | sphinx/directives.rst | 2109 | ||||
| -rw-r--r-- | sphinx/distutils.rst | 41 | ||||
| -rw-r--r-- | sphinx/embedding.rst | 62 | ||||
| -rw-r--r-- | sphinx/incompatibilities.rst | 198 | ||||
| -rw-r--r-- | sphinx/index.rst | 20 | ||||
| -rw-r--r-- | sphinx/installation.rst | 169 | ||||
| -rw-r--r-- | sphinx/introduction.rst | 169 | ||||
| -rw-r--r-- | sphinx/python_api.rst | 282 | ||||
| -rw-r--r-- | sphinx/specification_files.rst | 499 | ||||
| -rw-r--r-- | sphinx/using.rst | 662 |
16 files changed, 7998 insertions, 0 deletions
diff --git a/sphinx/annotations.rst b/sphinx/annotations.rst new file mode 100644 index 0000000..05ab847 --- /dev/null +++ b/sphinx/annotations.rst @@ -0,0 +1,805 @@ +Annotations +=========== + +In this section we describe each of the annotations that can be used in +specification files. + +Annotations can either be :ref:`argument annotations <ref-arg-annos>`, +:ref:`class annotations <ref-class-annos>`, :ref:`mapped type annotations +<ref-mapped-type-annos>`, :ref:`enum annotations <ref-enum-annos>`, +:ref:`exception annotations <ref-exception-annos>`, :ref:`function annotations +<ref-function-annos>`, :ref:`license annotations <ref-license-annos>`, +:ref:`typedef annotations <ref-typedef-annos>` or :ref:`variable annotations +<ref-variable-annos>` depending on the context in which they can be used. + +Annotations are placed between forward slashes (``/``). Multiple annotations +are comma separated within the slashes. + +Annotations have a type and, possibly, a value. The type determines the +format of the value. The name of an annotation and its value are separated by +``=``. + +Annotations can have one of the following types: + +*boolean* + This type of annotation has no value and is implicitly true. + +*name* + The value is a name that is compatible with a C/C++ identifier. In some + cases the value is optional. + +*dotted name* + The value is a name that is compatible with an identifier preceded by a + Python scope. + +*string* + The value is a double quoted string. + +*API range* + The value is the name of an API (defined using the :directive:`%API` + directive) separated by a range of version numbers with a colon. + + The range of version numbers is a pair of numbers separated by a hyphen + specifying the lower and upper bounds of the range. A version number is + within the range if it is greater or equal to the lower bound and less + than the upper bound. Each bound can be omitted meaning that the range is + unbounded in that direction. + + For example:: + + # This is part of the PyQt4 API up to but excluding v2. + void hex() /API=PyQt4:-2/ + + # This is part of the PyQt4 API starting from v2. + void hex() /PyName=hex_, API=PyQt4:2-/ + +The following example shows argument and function annotations:: + + void exec(QWidget * /Transfer/) /ReleaseGIL, PyName=call_exec/; + +Note that the current version of SIP does not complain about unknown +annotations, or annotations used out of their correct context. + + +.. _ref-arg-annos: + +Argument Annotations +-------------------- + +.. argument-annotation:: AllowNone + + This boolean annotation specifies that the value of the corresponding + argument (which should be either :stype:`SIP_PYCALLABLE`, + :stype:`SIP_PYDICT`, :stype:`SIP_PYLIST`, :stype:`SIP_PYSLICE`, + :stype:`SIP_PYTUPLE` or :stype:`SIP_PYTYPE`) may be ``None``. + + +.. argument-annotation:: Array + + This boolean annotation specifies that the corresponding argument refers + to an array. + + The argument should be either a pointer to a wrapped type, a ``char *`` or + a ``unsigned char *``. If the argument is a character array then the + annotation also implies the :aanno:`Encoding` annotation with an encoding + of ``"None"``. + + There must be a corresponding argument with the :aanno:`ArraySize` + annotation specified. The annotation may only be specified once in a list + of arguments. + + +.. argument-annotation:: ArraySize + + This boolean annotation specifies that the corresponding argument (which + should be either ``short``, ``unsigned short``, ``int``, ``unsigned``, + ``long`` or ``unsigned long``) refers to the size of an array. There must + be a corresponding argument with the :aanno:`Array` annotation specified. + The annotation may only be specified once in a list of arguments. + + +.. argument-annotation:: Constrained + + Python will automatically convert between certain compatible types. For + example, if a floating pointer number is expected and an integer supplied, + then the integer will be converted appropriately. This can cause problems + when wrapping C or C++ functions with similar signatures. For example:: + + // The wrapper for this function will also accept an integer argument + // which Python will automatically convert to a floating point number. + void foo(double); + + // The wrapper for this function will never get used. + void foo(int); + + This boolean annotation specifies that the corresponding argument (which + should be either ``bool``, ``int``, ``float``, ``double``, ``enum`` or a + wrapped class) must match the type without any automatic conversions. In + the context of a wrapped class the invocation of any + :directive:`%ConvertToTypeCode` is suppressed. + + The following example gets around the above problem:: + + // The wrapper for this function will only accept floating point + // numbers. + void foo(double /Constrained/); + + // The wrapper for this function will be used for anything that Python + // can convert to an integer, except for floating point numbers. + void foo(int); + + +.. argument-annotation:: DocType + + .. versionadded:: 4.10 + + This string annotation specifies the type of the argument as it will appear + in any generated docstrings. It is usually used with arguments of type + :stype:`SIP_PYOBJECT` to provide a more specific type. + + +.. argument-annotation:: DocValue + + .. versionadded:: 4.10 + + This string annotation specifies the default value of the argument as it + will appear in any generated docstrings. + + +.. argument-annotation:: Encoding + + This string annotation specifies that the corresponding argument (which + should be either ``char``, ``const char``, ``char *`` or ``const char *``) + refers to an encoded character or ``'\0'`` terminated encoded string with + the specified encoding. The encoding can be either ``"ASCII"``, + ``"Latin-1"``, ``"UTF-8"`` or ``"None"``. An encoding of ``"None"`` means + that the corresponding argument refers to an unencoded character or string. + + The default encoding is specified by the :directive:`%DefaultEncoding` + directive. If the directive is not specified then ``None`` is used. + + Python v3 will use the ``bytes`` type to represent the argument if the + encoding is ``"None"`` and the ``str`` type otherwise. + + Python v2 will use the ``str`` type to represent the argument if the + encoding is ``"None"`` and the ``unicode`` type otherwise. + + +.. argument-annotation:: GetWrapper + + This boolean annotation is only ever used in conjunction with handwritten + code specified with the :directive:`%MethodCode` directive. It causes an + extra variable to be generated for the corresponding argument which is a + pointer to the Python object that wraps the argument. + + See the :directive:`%MethodCode` directive for more detail. + + +.. argument-annotation:: In + + This boolean annotation is used to specify that the corresponding argument + (which should be a pointer type) is used to pass a value to the function. + + For pointers to wrapped C structures or C++ class instances, ``char *`` and + ``unsigned char *`` then this annotation is assumed unless the :aanno:`Out` + annotation is specified. + + For pointers to other types then this annotation must be explicitly + specified if required. The argument will be dereferenced to obtain the + actual value. + + Both :aanno:`In` and :aanno:`Out` may be specified for the same argument. + + +.. argument-annotation:: KeepReference + + This boolean annotation is used to specify that a reference to the + corresponding argument should be kept to ensure that the object is not + garbage collected. If the method is called again with a new argument then + the reference to the previous argument is discarded. Note that ownership + of the argument is not changed. + + +.. argument-annotation:: NoCopy + + .. versionadded:: 4.10.1 + + This boolean annotation is used with arguments of virtual methods that are + a ``const`` reference to a class. Normally, if the class defines a copy + constructor then a copy of the returned reference is automatically created + and wrapped before being passed to a Python reimplementation of the method. + The copy will be owned by Python. This means that the reimplementation may + take a reference to the argument without having to make an explicit copy. + + If the annotation is specified then the copy is not made and the original + reference is wrapped instead and will be owned by C++. + + +.. argument-annotation:: Out + + This boolean annotation is used to specify that the corresponding argument + (which should be a pointer type) is used by the function to return a value + as an element of a tuple. + + For pointers to wrapped C structures or C++ class instances, ``char *`` and + ``unsigned char *`` then this annotation must be explicitly specified if + required. + + For pointers to other types then this annotation is assumed unless the + :aanno:`In` annotation is specified. + + Both :aanno:`In` and :aanno:`Out` may be specified for the same argument. + + +.. argument-annotation:: ResultSize + + This boolean annotation is used with functions or methods that return a + ``void *`` or ``const void *``. It identifies an argument that defines the + size of the block of memory whose address is being returned. This allows + the ``sip.voidptr`` object that wraps the address to support the Python + buffer protocol and allows the memory to be read and updated when wrapped + by the Python ``buffer()`` builtin. + + +.. argument-annotation:: SingleShot + + This boolean annotation is used only with arguments of type + :stype:`SIP_RXOBJ_CON` to specify that the signal connected to the slot + will only ever be emitted once. This prevents a certain class of memory + leaks. + + +.. argument-annotation:: Transfer + + This boolean annotation is used to specify that ownership of the + corresponding argument (which should be a wrapped C structure or C++ class + instance) is transferred from Python to C++. In addition, if the argument + is of a class method, then it is associated with the class instance with + regard to the cyclic garbage collector. + + See :ref:`ref-object-ownership` for more detail. + + +.. argument-annotation:: TransferBack + + This boolean annotation is used to specify that ownership of the + corresponding argument (which should be a wrapped C structure or C++ class + instance) is transferred back to Python from C++. In addition, any + association of the argument with regard to the cyclic garbage collector + with another instance is removed. + + See :ref:`ref-object-ownership` for more detail. + + +.. argument-annotation:: TransferThis + + This boolean annotation is only used in C++ constructors or methods. In + the context of a constructor or factory method it specifies that ownership + of the instance being created is transferred from Python to C++ if the + corresponding argument (which should be a wrapped C structure or C++ class + instance) is not ``None``. In addition, the newly created instance is + associated with the argument with regard to the cyclic garbage collector. + + In the context of a non-factory method it specifies that ownership of + ``this`` is transferred from Python to C++ if the corresponding argument is + not ``None``. If it is ``None`` then ownership is transferred to Python. + + The annotation may be used more that once, in which case ownership is + transferred to last instance that is not ``None``. + + See :ref:`ref-object-ownership` for more detail. + + +.. _ref-class-annos: + +Class Annotations +----------------- + +.. class-annotation:: Abstract + + This boolean annotation is used to specify that the class has additional + pure virtual methods that have not been specified and so it cannot be + instantiated or sub-classed from Python. + + +.. class-annotation:: AllowNone + + .. versionadded:: 4.8.2 + + Normally when a Python object is converted to a C/C++ instance ``None`` + is handled automatically before the class's + :directive:`%ConvertToTypeCode` is called. This boolean annotation + specifies that the handling of ``None`` will be left to the + :directive:`%ConvertToTypeCode`. The annotation is ignored if the class + does not have any :directive:`%ConvertToTypeCode`. + + +.. class-annotation:: API + + .. versionadded:: 4.9 + + This API range annotation is used to specify an API and corresponding + range of version numbers that the class is enabled for. + + If a class or mapped type has different implementations enabled for + different ranges of version numbers then those ranges must not overlap. + + See :ref:`ref-incompat-apis` for more detail. + + +.. class-annotation:: DelayDtor + + This boolean annotation is used to specify that the class's destructor + should not be called until the Python interpreter exits. It would normally + only be applied to singleton classes. + + When the Python interpreter exits the order in which any wrapped instances + are garbage collected is unpredictable. However, the underlying C or C++ + instances may need to be destroyed in a certain order. If this annotation + is specified then when the wrapped instance is garbage collected the C or + C++ instance is not destroyed but instead added to a list of delayed + instances. When the interpreter exits then the function + :cfunc:`sipDelayedDtors()` is called with the list of delayed instances. + :cfunc:`sipDelayedDtors()` can then choose to call (or ignore) the + destructors in any desired order. + + The :cfunc:`sipDelayedDtors()` function must be specified using the + :directive:`%ModuleCode` directive. + +.. cfunction:: void sipDelayedDtors(const sipDelayedDtor *dd_list) + + :param dd_list: + the linked list of delayed instances. + +.. ctype:: sipDelayedDtor + + This structure describes a particular delayed destructor. + + .. cmember:: const char *dd_name + + This is the name of the class excluding any package or module name. + + .. cmember:: void *dd_ptr + + This is the address of the C or C++ instance to be destroyed. It's + exact type depends on the value of :cmember:`dd_isderived`. + + .. cmember:: int dd_isderived + + This is non-zero if the type of :cmember:`dd_ptr` is actually the + generated derived class. This allows the correct destructor to be + called. See :ref:`ref-derived-classes`. + + .. cmember:: sipDelayedDtor *dd_next + + This is the address of the next entry in the list or zero if this is + the last one. + + Note that the above applies only to C and C++ instances that are owned by + Python. + + +.. class-annotation:: Deprecated + + This boolean annotation is used to specify that the class is deprecated. + It is the equivalent of annotating all the class's constructors, function + and methods as being deprecated. + + +.. class-annotation:: External + + This boolean annotation is used to specify that the class is defined in + another module. Declarations of external classes are private to the module + in which they appear. + + +.. class-annotation:: Metatype + + This dotted name annotation specifies the name of the Python type object + (i.e. the value of the ``tp_name`` field) used as the meta-type used when + creating the type object for this C structure or C++ type. + + See the section :ref:`ref-types-metatypes` for more details. + + +.. class-annotation:: NoDefaultCtors + + This boolean annotation is used to suppress the automatic generation of + default constructors for the class. + + +.. class-annotation:: PyName + + This name annotation specifies an alternative name for the class being + wrapped which is used when it is referred to from Python. It is required + when a class name is the same as a Python keyword. It may also be used to + avoid name clashes with other objects (e.g. enums, exceptions, functions) + that have the same name in the same C++ scope. + + +.. class-annotation:: Supertype + + This dotted name annotation specifies the name of the Python type object + (i.e. the value of the ``tp_name`` field) used as the super-type used when + creating the type object for this C structure or C++ type. + + See the section :ref:`ref-types-metatypes` for more details. + + +.. _ref-mapped-type-annos: + +Mapped Type Annotations +----------------------- + +.. mapped-type-annotation:: AllowNone + + Normally when a Python object is converted to a C/C++ instance ``None`` + is handled automatically before the mapped type's + :directive:`%ConvertToTypeCode` is called. This boolean annotation + specifies that the handling of ``None`` will be left to the + :directive:`%ConvertToTypeCode`. + + +.. mapped-type-annotation:: API + + .. versionadded:: 4.9 + + This API range annotation is used to specify an API and corresponding + range of version numbers that the mapped type is enabled for. + + If a class or mapped type has different implementations enabled for + different ranges of version numbers then those ranges must not overlap. + + See :ref:`ref-incompat-apis` for more detail. + + +.. mapped-type-annotation:: DocType + + .. versionadded:: 4.10 + + This string annotation specifies the name of the type as it will appear in + any generated docstrings. + + +.. mapped-type-annotation:: NoRelease + + This boolean annotation is used to specify that the mapped type does not + support the :cfunc:`sipReleaseType()` function. Any + :directive:`%ConvertToTypeCode` should not create temporary instances of + the mapped type, i.e. it should not return :cmacro:`SIP_TEMPORARY`. + + +.. _ref-enum-annos: + +Enum Annotations +---------------- + +.. enum-annotation:: PyName + + This name annotation specifies an alternative name for the enum or enum + member being wrapped which is used when it is referred to from Python. It + is required when an enum or enum member name is the same as a Python + keyword. It may also be used to avoid name clashes with other objects + (e.g. classes, exceptions, functions) that have the same name in the same + C++ scope. + + +.. _ref-exception-annos: + +Exception Annotations +--------------------- + +.. exception-annotation:: Default + + This boolean annotation specifies that the exception being defined will be + used as the default exception to be caught if a function or constructor + does not have a ``throw`` clause. + +.. exception-annotation:: PyName + + This name annotation specifies an alternative name for the exception being + defined which is used when it is referred to from Python. It is required + when an exception name is the same as a Python keyword. It may also be + used to avoid name clashes with other objects (e.g. classes, enums, + functions) that have the same name. + + +.. _ref-function-annos: + +Function Annotations +-------------------- + +.. function-annotation:: API + + .. versionadded:: 4.9 + + This API range annotation is used to specify an API and corresponding + range of version numbers that the function is enabled for. + + See :ref:`ref-incompat-apis` for more detail. + + +.. function-annotation:: AutoGen + + This optional name annotation is used with class methods to specify that + the method be automatically included in all sub-classes. The value is the + name of a feature (specified using the :directive:`%Feature` directive) + which must be enabled for the method to be generated. + + +.. function-annotation:: Default + + This boolean annotation is only used with C++ constructors. Sometimes SIP + needs to create a class instance. By default it uses a constructor with no + compulsory arguments if one is specified. (SIP will automatically generate + a constructor with no arguments if no constructors are specified.) This + annotation is used to explicitly specify which constructor to use. Zero is + passed as the value of any arguments to the constructor. + + +.. function-annotation:: Deprecated + + This boolean annotation is used to specify that the constructor or function + is deprecated. A deprecation warning is issued whenever the constructor or + function is called. + + +.. function-annotation:: DocType + + .. versionadded:: 4.10 + + This string annotation specifies the name of the type of the returned value + as it will appear in any generated docstrings. It is usually used with + values of type :stype:`SIP_PYOBJECT` to provide a more specific type. + + +.. function-annotation:: Factory + + This boolean annotation specifies that the value returned by the function + (which should be a wrapped C structure or C++ class instance) is a newly + created instance and is owned by Python. + + See :ref:`ref-object-ownership` for more detail. + + +.. function-annotation:: HoldGIL + + This boolean annotation specifies that the Python Global Interpreter Lock + (GIL) is not released before the call to the underlying C or C++ function. + See :ref:`ref-gil` and the :fanno:`ReleaseGIL` annotation. + + +.. function-annotation:: KeywordArgs + + .. versionadded:: 4.10 + + This boolean annotation specifies that the argument parser generated for + this function will support passing the parameters using Python's keyword + argument syntax. Keyword arguments cannot be used for functions that have + unnamed arguments or use an ellipsis to designate that the function has a + variable number of arguments. + + +.. function-annotation:: __len__ + + .. versionadded:: 4.10.3 + + This boolean annotation specifies that a ``__len__()`` method should be + automatically generated that will use the method being annotated to compute + the value that the ``__len__()`` method will return. + + +.. function-annotation:: NewThread + + This boolean annotation specifies that the function will create a new + thread. + + +.. function-annotation:: NoArgParser + + This boolean annotation is used with methods and global functions to + specify that the supplied :directive:`%MethodCode` will handle the parsing + of the arguments. + + +.. function-annotation:: NoCopy + + .. versionadded:: 4.10.1 + + This boolean annotation is used with methods and global functions that + return a ``const`` reference to a class. Normally, if the class defines a + copy constructor then a copy of the returned reference is automatically + created and wrapped. The copy will be owned by Python. + + If the annotation is specified then the copy is not made and the original + reference is wrapped instead and will be owned by C++. + + +.. function-annotation:: NoDerived + + This boolean annotation is only used with C++ constructors. In many cases + SIP generates a derived class for each class being wrapped (see + :ref:`ref-derived-classes`). This derived class contains constructors with + the same C++ signatures as the class being wrapped. Sometimes you may want + to define a Python constructor that has no corresponding C++ constructor. + This annotation is used to suppress the generation of the constructor in + the derived class. + + +.. function-annotation:: NoKeywordArgs + + .. versionadded:: 4.10 + + This boolean annotation specifies that the argument parser generated for + this function will not support passing the parameters using Python's + keyword argument syntax. In other words, the argument parser will only + support only normal positional arguments. This annotation is useful when + the default setting of allowing keyword arguments has been changed via the + command line, but you would still like certain functions to only support + positional arguments. + + +.. function-annotation:: Numeric + + This boolean annotation specifies that the operator should be interpreted + as a numeric operator rather than a sequence operator. Python uses the + ``+`` operator for adding numbers and concatanating sequences, and the + ``*`` operator for multiplying numbers and repeating sequences. SIP tries + to work out which is meant by looking at other operators that have been + defined for the type. If it finds either ``-``, ``-=``, ``/``, ``/=``, + ``%`` or ``%=`` defined then it assumes that ``+``, ``+=``, ``*`` and + ``*=`` should be numeric operators. Otherwise, if it finds either ``[]``, + :meth:`__getitem__`, :meth:`__setitem__` or :meth:`__delitem__` defined + then it assumes that they should be sequence operators. This annotation is + used to force SIP to treat the operator as numeric. + + +.. function-annotation:: PostHook + + This name annotation is used to specify the name of a Python builtin that + is called immediately after the call to the underlying C or C++ function or + any handwritten code. The builtin is not called if an error occurred. It + is primarily used to integrate with debuggers. + + +.. function-annotation:: PreHook + + This name annotation is used to specify the name of a Python builtin that + is called immediately after the function's arguments have been successfully + parsed and before the call to the underlying C or C++ function or any + handwritten code. It is primarily used to integrate with debuggers. + + +.. function-annotation:: PyName + + This name annotation specifies an alternative name for the function being + wrapped which is used when it is referred to from Python. It is required + when a function or method name is the same as a Python keyword. It may + also be used to avoid name clashes with other objects (e.g. classes, enums, + exceptions) that have the same name in the same C++ scope. + + +.. function-annotation:: ReleaseGIL + + This boolean annotation specifies that the Python Global Interpreter Lock + (GIL) is released before the call to the underlying C or C++ function and + reacquired afterwards. It should be used for functions that might block or + take a significant amount of time to execute. See :ref:`ref-gil` and the + :fanno:`HoldGIL` annotation. + + +.. function-annotation:: Transfer + + This boolean annotation specifies that ownership of the value returned by + the function (which should be a wrapped C structure or C++ class instance) + is transferred to C++. It is only used in the context of a class + constructor or a method. + + In the case of methods returned values (unless they are new references to + already wrapped values) are normally owned by C++ anyway. However, in + addition, an association between the returned value and the instance + containing the method is created with regard to the cyclic garbage + collector. + + See :ref:`ref-object-ownership` for more detail. + + +.. function-annotation:: TransferBack + + This boolean annotation specifies that ownership of the value returned by + the function (which should be a wrapped C structure or C++ class instance) + is transferred back to Python from C++. Normally returned values (unless + they are new references to already wrapped values) are owned by C++. In + addition, any association of the returned value with regard to the cyclic + garbage collector with another instance is removed. + + See :ref:`ref-object-ownership` for more detail. + + +.. function-annotation:: TransferThis + + This boolean annotation specifies that ownership of ``this`` is transferred + from Python to C++. + + See :ref:`ref-object-ownership` for more detail. + + +.. _ref-license-annos: + +License Annotations +------------------- + +.. license-annotation:: Licensee + + This optional string annotation specifies the license's licensee. No + restrictions are placed on the contents of the string. + + See the :directive:`%License` directive. + + +.. license-annotation:: Signature + + This optional string annotation specifies the license's signature. No + restrictions are placed on the contents of the string. + + See the :directive:`%License` directive. + + +.. license-annotation:: Timestamp + + This optional string annotation specifies the license's timestamp. No + restrictions are placed on the contents of the string. + + See the :directive:`%License` directive. + + +.. license-annotation:: Type + + This string annotation specifies the license's type. No restrictions are + placed on the contents of the string. + + See the :directive:`%License` directive. + + +.. _ref-typedef-annos: + +Typedef Annotations +------------------- + +.. typedef-annotation:: NoTypeName + + This boolean annotation specifies that the definition of the type rather + than the name of the type being defined should be used in the generated + code. + + Normally a typedef would be defined as follows:: + + typedef bool MyBool; + + This would result in ``MyBool`` being used in the generated code. + + Specifying the annotation means that ``bool`` will be used in the generated + code instead. + + +.. _ref-variable-annos: + +Variable Annotations +-------------------- + +.. variable-annotation:: DocType + + .. versionadded:: 4.10 + + This string annotation specifies the name of the type of the variable as it + will appear in any generated docstrings. It is usually used with variables + of type :stype:`SIP_PYOBJECT` to provide a more specific type. + + +.. variable-annotation:: PyName + + This name annotation specifies an alternative name for the variable being + wrapped which is used when it is referred to from Python. It is required + when a variable name is the same as a Python keyword. It may also be used + to avoid name clashes with other objects (e.g. classes, functions) that + have the same name in the same C++ scope. diff --git a/sphinx/build_system.rst b/sphinx/build_system.rst new file mode 100644 index 0000000..292836a --- /dev/null +++ b/sphinx/build_system.rst @@ -0,0 +1,843 @@ +.. _ref-build-system: + +The Build System +================ + +.. module:: sipconfig + +The purpose of the build system is to make it easy for you to write +configuration scripts in Python for your own bindings. The build system takes +care of the details of particular combinations of platform and compiler. It +supports over 50 different platform/compiler combinations. + +The build system is implemented as a pure Python module called :mod:`sipconfig` +that contains a number of classes and functions. Using this module you can +write bespoke configuration scripts (e.g. PyQt's ``configure.py``) or use it +with other Python based build systems (e.g. +`Distutils <http://www.python.org/sigs/distutils-sig/distutils.html>`_ and +`SCons <http://www.scons.org>`_). + +An important feature of SIP is the ability to generate bindings that are built +on top of existing bindings. For example, both +`PyKDE <http://www.riverbankcomputing.com/software/pykde/>`_ and +`PyQwt <http://pyqwt.sourceforge.net/>`_ are built on top of PyQt but all three +packages are maintained by different developers. To make this easier PyQt +includes its own configuration module, ``pyqtconfig``, that contains additional +classes intended to be used by the configuration scripts of bindings built on +top of PyQt. The SIP build system includes facilities that do a lot of the +work of creating these additional configuration modules. + + +.. function:: create_config_module(module, template, content[, macros=None]) + + This creates a configuration module (e.g. ``pyqtconfig``) from a template + file and a string. + + :param module: + the name of the configuration module file to create. + :param template: + the name of the template file. + :param content: + a string which replaces every occurence of the pattern + ``@SIP_CONFIGURATION@`` in the template file. The content string is + usually created from a Python dictionary using + :func:`sipconfig.create_content()`. *content* may also be a + dictionary, in which case :func:`sipconfig.create_content()` is + automatically called to convert it to a string. + :param macros: + an optional dictionary of platform specific build macros. It is only + used if :func:`sipconfig.create_content()` is called automatically to + convert a *content* dictionary to a string. + + +.. function:: create_content(dict[, macros=None]) -> string + + This converts a Python dictionary to a string that can be parsed by the + Python interpreter and converted back to an equivalent dictionary. It is + typically used to generate the content string for + :func:`sipconfig.create_config_module()`. + + :param dict: + the Python dictionary to convert. + :param macros: + the optional dictionary of platform specific build macros. + :return: + the string representation of the dictionary. + + +.. function:: create_wrapper(script, wrapper[, gui=0[, use_arch='']]) -> string + + This creates a platform dependent executable wrapper around a Python + script. + + :param script: + the full pathname of the script. + :param wrapper: + the full pathname of the wrapper to create, excluding any platform + specific extension. + :param gui: + is non-zero if a GUI enabled version of the interpreter should be used + on platforms that require it. + :param use_arch: + is the MacOS/X architecture to invoke python with. + :return: + the platform specific name of the wrapper. + + +.. function:: error(msg) + + This displays an error message on ``stderr`` and calls ``sys.exit(1)``. + + :param msg: + the text of the message and should not include any newline characters. + + +.. function:: format(msg[, leftmargin=0[, rightmargin=78]]) -> string + + This formats a message by inserting newline characters at appropriate + places. + + :param msg: + the text of the message and should not include any newline characters. + :param leftmargin: + the optional position of the left margin. + :param rightmargin: + the optional position of the right margin. + :return: + the formatted message. + + +.. function:: inform(msg) + + This displays an information message on ``stdout``. + + :param msg: + the text of the message and should not include any newline characters. + + +.. function:: parse_build_macros(filename, names[, overrides=None[, properties=None]]) -> dict + + This parses a ``qmake`` compatible file of build system macros and converts + it to a dictionary. A macro is a name/value pair. Individual macros may + be augmented or replaced. + + :param filename: + the name of the file to parse. + :param names: + the list of the macro names to extract from the file. + :param overrides: + the optional list of macro names and values that modify those found in + the file. They are of the form ``name=value`` (in which case the value + replaces the value found in the file) or ``name+=value`` (in which case + the value is appended to the value found in the file). + :param properties: + the optional dictionary of property name and values that are used to + resolve any expressions of the form ``$[name]`` in the file. + :return: + the dictionary of parsed macros or ``None`` if any of the overrides + were invalid. + + +.. function:: read_version(filename, description[, numdefine=None[, strdefine=None]]) -> integer, string + + This extracts version information for a package from a file, usually a C or + C++ header file. The version information must each be specified as a + ``#define`` of a numeric (hexadecimal or decimal) value and/or a string + value. + + :param filename: + the name of the file to read. + :param description: + a descriptive name of the package used in error messages. + :param numdefine: + the optional name of the ``#define`` of the version as a number. If it + is ``None`` then the numeric version is ignored. + :param strdefine: + the optional name of the ``#define`` of the version as a string. If it + is ``None`` then the string version is ignored. + :return: + a tuple of the numeric and string versions. :func:`sipconfig.error()` + is called if either were required but could not be found. + + +.. function:: version_to_sip_tag(version, tags, description) -> string + + This converts a version number to a SIP version tag. SIP uses the + :directive:`%Timeline` directive to define the chronology of the different + versions of the C/C++ library being wrapped. Typically it is not necessary + to define a version tag for every version of the library, but only for + those versions that affect the library's API as SIP sees it. + + :param version: + the numeric version number of the C/C++ library being wrapped. If it + is negative then the latest version is assumed. (This is typically + useful if a snapshot is indicated by a negative version number.) + :param tags: + the dictionary of SIP version tags keyed by the corresponding C/C++ + library version number. The tag used is the one with the smallest key + (i.e. earliest version) that is greater than *version*. + :param description: + a descriptive name of the C/C++ library used in error messages. + :return: + the SIP version tag. :func:`sipconfig.error()` is called if the C/C++ + library version number did not correspond to a SIP version tag. + + +.. function:: version_to_string(v) -> string + + This converts a 3 part version number encoded as a hexadecimal value to a + string. + + :param v: + the version number. + :return: + a string. + + +.. class:: Configuration + + This class encapsulates configuration values that can be accessed as + instance objects. A sub-class may provide a dictionary of additional + configuration values in its constructor the elements of which will have + precedence over the super-class's values. + + The following configuration values are provided: + + .. attribute:: default_bin_dir + + The name of the directory where executables should be installed by + default. + + .. attribute:: default_mod_dir + + The name of the directory where SIP generated modules should be + installed by default. + + .. attribute:: default_sip_dir + + The name of the base directory where the ``.sip`` files for SIP + generated modules should be installed by default. A sub-directory with + the same name as the module should be created and its ``.sip`` files + should be installed in the sub-directory. The ``.sip`` files only need + to be installed if you might want to build other bindings based on + them. + + .. attribute:: platform + + The name of the platform/compiler for which the build system has been + configured for. + + .. attribute:: py_conf_inc_dir + + The name of the directory containing the ``pyconfig.h`` header file. + + .. attribute:: py_inc_dir + + The name of the directory containing the ``Python.h`` header file. + + .. attribute:: py_lib_dir + + The name of the directory containing the Python interpreter library. + + .. attribute:: py_version + + The Python version as a 3 part hexadecimal number (e.g. v2.3.3 is + represented as ``0x020303``). + + .. attribute:: sip_bin + + The full pathname of the SIP executable. + + .. attribute:: sip_config_args + + The command line passed to ``configure.py`` when SIP was configured. + + .. attribute:: sip_inc_dir + + The name of the directory containing the ``sip.h`` header file. + + .. attribute:: sip_mod_dir + + The name of the directory containing the SIP module. + + .. attribute:: sip_version + + The SIP version as a 3 part hexadecimal number (e.g. v4.0.0 is + represented as ``0x040000``). + + .. attribute:: sip_version_str + + The SIP version as a string. For development snapshots it will start + with ``snapshot-``. + + .. attribute:: universal + + The name of the MacOS/X SDK used when creating universal binaries. + + .. attribute:: arch + + The space separated MacOS/X architectures to build. + + .. method:: __init__([sub_cfg=None]) + + :param sub_cfg: + an optional list of sub-class configurations. It should only be + used by the ``__init__()`` method of a sub-class to append its own + dictionary of configuration values before passing the list to its + super-class. + + .. method:: build_macros() -> dict + + Get the dictionary of platform specific build macros. + + :return: + the macros dictionary. + + .. method:: set_build_macros(macros) + + Set the dictionary of platform specific build macros to be used when + generating Makefiles. Normally there is no need to change the default + macros. + + :param macros: + the macros dictionary. + + +.. class:: Makefile + + This class encapsulates a Makefile. It is intended to be sub-classed to + generate Makefiles for particular purposes. It handles all platform and + compiler specific flags, but allows them to be adjusted to suit the + requirements of a particular module or program. These are defined using a + number of macros which can be accessed as instance attributes. + + The following instance attributes are provided to help in fine tuning the + generated Makefile: + + .. attribute:: chkdir + + A string that will check for the existence of a directory. + + .. attribute:: config + + A reference to the *configuration* argument that was passed to + :meth:`Makefile.__init__`. + + .. attribute:: console + + A reference to the *console* argument that was passed to the + :meth:`Makefile.__init__`. + + .. attribute:: copy + + A string that will copy a file. + + .. attribute:: extra_cflags + + A list of additional flags passed to the C compiler. + + .. attribute:: extra_cxxflags + + A list of additional flags passed to the C++ compiler. + + .. attribute:: extra_defines + + A list of additional macro names passed to the C/C++ preprocessor. + + .. attribute:: extra_include_dirs + + A list of additional include directories passed to the C/C++ + preprocessor. + + .. attribute:: extra_lflags + + A list of additional flags passed to the linker. + + .. attribute:: extra_lib_dirs + + A list of additional library directories passed to the linker. + + .. attribute:: extra_libs + + A list of additional libraries passed to the linker. The names of the + libraries must be in platform neutral form (i.e. without any platform + specific prefixes, version numbers or extensions). + + .. attribute:: generator + + A string that defines the platform specific style of Makefile. The + only supported values are ``UNIX``, ``MSVC``, ``MSVC.NET``, ``MINGW`` + and ``BMAKE``. + + .. attribute:: mkdir + + A string that will create a directory. + + .. attribute:: rm + + A string that will remove a file. + + .. method:: __init__(configuration[, console=0[, qt=0[, opengl=0[, python=0[, threaded=0[, warnings=None[, debug=0[, dir=None[, makefile="Makefile"[, installs=None[, universal=None[, arch=None]]]]]]]]]]]]) + + :param configuration: + the current configuration and is an instance of the + :class:`Configuration` class or a sub-class. + :param console: + is set if the target is a console (rather than GUI) target. This + only affects Windows and is ignored on other platforms. + :param qt: + is set if the target uses Qt. For Qt v4 a list of Qt libraries may + be specified and a simple non-zero value implies QtCore and QtGui. + :param opengl: + is set if the target uses OpenGL. + :param python: + is set if the target uses Python.h. + :param threaded: + is set if the target requires thread support. It is set + automatically if the target uses Qt and Qt has thread support + enabled. + :param warnings: + is set if compiler warning messages should be enabled. The default + of ``None`` means that warnings are enabled for SIP v4.x and + disabled for SIP v3.x. + :param debug: + is set if debugging symbols should be generated. + :param dir: + the name of the directory where build files are read from (if they + are not absolute file names) and Makefiles are written to. The + default of ``None`` means the current directory is used. + :param makefile: + the name of the generated Makefile. + :param installs: + the list of extra install targets. Each element is a two part + list, the first of which is the source and the second is the + destination. If the source is another list then it is a list of + source files and the destination is a directory. + :param universal: + the name of the SDK if universal binaries are to be created under + MacOS/X. If it is ``None`` then the value is taken from the + configuration. + :param arch: + the space separated MacOS/X architectures to build. If it is + ``None`` then the value is taken from the configuration. + + .. method:: clean_build_file_objects(mfile, build) + + This generates the Makefile commands that will remove any files + generated during the build of the default target. + + :param mfile: + the Python file object of the Makefile. + :param build: + the dictionary created from parsing the build file. + + .. method:: finalise() + + This is called just before the Makefile is generated to ensure that it + is fully configured. It must be reimplemented by a sub-class. + + .. method:: generate() + + This generates the Makefile. + + .. method:: generate_macros_and_rules(mfile) + + This is the default implementation of the Makefile macros and rules + generation. + + :param mfile: + the Python file object of the Makefile. + + .. method:: generate_target_clean(mfile) + + This is the default implementation of the Makefile clean target + generation. + + :param mfile: + the Python file object of the Makefile. + + .. method:: generate_target_default(mfile) + + This is the default implementation of the Makefile default target + generation. + + :param mfile: + the Python file object of the Makefile. + + .. method:: generate_target_install(mfile) + + This is the default implementation of the Makefile install target + generation. + + :param mfile: + the Python file object of the Makefile. + + .. method:: install_file(mfile, src, dst[, strip=0]) + + This generates the Makefile commands to install one or more files to a + directory. + + :param mfile: + the Python file object of the Makefile. + :param src: + the name of a single file to install or a list of a number of files + to install. + :param dst: + the name of the destination directory. + :param strip: + is set if the files should be stripped of unneeded symbols after + having been installed. + + .. method:: optional_list(name) -> list + + This returns an optional Makefile macro as a list. + + :param name: + the name of the macro. + :return: + the macro as a list. + + .. method:: optional_string(name[, default=""]) + + This returns an optional Makefile macro as a string. + + :param name: + the name of the macro. + :param default: + the optional default value of the macro. + :return: + the macro as a string. + + .. method:: parse_build_file(filename) -> dict + + This parses a build file (created with the :option:`-b <sip -b>` SIP + command line option) and converts it to a dictionary. It can also + validate an existing dictionary created through other means. + + :param filename: is the name of the build file, or is a dictionary to + be validated. A valid dictionary will contain the name of the + target to build (excluding any platform specific extension) keyed + by ``target``; the names of all source files keyed by ``sources``; + and, optionally, the names of all header files keyed by + ``headers``. + :return: + a dictionary corresponding to the parsed build file. + + .. method:: platform_lib(clib[, framework=0]) -> string + + This converts a library name to a platform specific form. + + :param clib: + the name of the library in cannonical form. + :param framework: + is set if the library is implemented as a MacOS framework. + :return: + the platform specific name. + + .. method:: ready() + + This is called to ensure that the Makefile is fully configured. It is + normally called automatically when needed. + + .. method:: required_string(name) -> string + + This returns a required Makefile macro as a string. + + :param name: + the name of the macro. + :return: + the macro as a string. An exception is raised if the macro does + not exist or has an empty value. + + +.. class:: ModuleMakefile + + This class is derived from :class:`sipconfig.Makefile`. + + This class encapsulates a Makefile to build a generic Python extension + module. + + .. method:: __init__(self, configuration, build_file[, install_dir=None[, static=0[, console=0[, opengl=0[, threaded=0[, warnings=None[, debug=0[, dir=None[, makefile="Makefile"[, installs=None[, strip=1[, export_all=0[, universal=None[, arch=None]]]]]]]]]]]]]]) + + :param configuration: + see :meth:`sipconfig.Makefile.__init__`. + :param build_file: + the name of the build file. Build files are generated using the + :option:`-b <sip -b>` SIP command line option. + :param install_dir: + the name of the directory where the module will be optionally + installed. + :param static: + is set if the module should be built as a static library (see + :ref:`ref-builtin`). + :param console: + see :meth:`sipconfig.Makefile.__init__`. + :param qt: + see :meth:`sipconfig.Makefile.__init__`. + :param opengl: + see :meth:`sipconfig.Makefile.__init__`. + :param threaded: + see :meth:`sipconfig.Makefile.__init__`. + :param warnings: + see :meth:`sipconfig.Makefile.__init__`. + :param debug: + see :meth:`sipconfig.Makefile.__init__`. + :param dir: + see :meth:`sipconfig.Makefile.__init__`. + :param makefile: + see :meth:`sipconfig.Makefile.__init__`. + :param installs: + see :meth:`sipconfig.Makefile.__init__`. + :param strip: + is set if the module should be stripped of unneeded symbols after + installation. It is ignored if either *debug* or *static* is set, + or if the platform doesn't support it. + :param export_all: + is set if all of the module's symbols should be exported rather + than just the module's initialisation function. Exporting all + symbols increases the size of the module and slows down module load + times but may avoid problems with modules that use C++ exceptions. + All symbols are exported if either *debug* or *static* is set, or + if the platform doesn't support it. + :param universal: + see :meth:`sipconfig.Makefile.__init__`. + :param arch: + see :meth:`sipconfig.Makefile.__init__`. + + .. method:: finalise() + + This is a reimplementation of :meth:`sipconfig.Makefile.finalise`. + + .. method:: generate_macros_and_rules(mfile) + + This is a reimplementation of + :meth:`sipconfig.Makefile.generate_macros_and_rules`. + + .. method:: generate_target_clean(mfile) + + This is a reimplementation of + :meth:`sipconfig.Makefile.generate_target_clean`. + + .. method:: generate_target_default(mfile) + + This is a reimplementation of + :meth:`sipconfig.Makefile.generate_target_default`. + + .. method:: generate_target_install(mfile) + + This is a reimplementation of + :meth:`sipconfig.Makefile.generate_target_install`. + + .. method:: module_as_lib(mname) -> string + + This gets the name of a SIP v3.x module for when it is used as a + library to be linked against. An exception will be raised if it is + used with SIP v4.x modules. + + :param mname: + the name of the module. + :return: + the corresponding library name. + + +.. class:: ParentMakefile + + This class is derived from :class:`sipconfig.Makefile`. + + This class encapsulates a Makefile that sits above a number of other + Makefiles in sub-directories. + + .. method:: __init__(self, configuration, subdirs[, dir=None[, makefile[="Makefile"[, installs=None]]]]) + + :param configuration: + see :meth:`sipconfig.Makefile.__init__`. + :param subdirs: + the sequence of sub-directories. + :param dir: + see :meth:`sipconfig.Makefile.__init__`. + :param makefile: + see :meth:`sipconfig.Makefile.__init__`. + :param installs: + see :meth:`sipconfig.Makefile.__init__`. + + .. method:: generate_macros_and_rules(mfile) + + This is a reimplementation of + :meth:`sipconfig.Makefile.generate_macros_and_rules`. + + .. method:: generate_target_clean(mfile) + + This is a reimplementation of + :meth:`sipconfig.Makefile.generate_target_clean`. + + .. method:: generate_target_default(mfile) + + This is a reimplementation of + :meth:`sipconfig.Makefile.generate_target_default`. + + .. method:: generate_target_install(mfile) + + This is a reimplementation of + :meth:`sipconfig.Makefile.generate_target_install`. + +.. class:: ProgramMakefile + + This class is derived from :class:`sipconfig.Makefile`. + + This class encapsulates a Makefile to build an executable program. + + .. method:: __init__(configuration[, build_file=None[, install_dir=None[, console=0[, qt=0[, opengl=0[, python=0[, threaded=0[, warnings=None[, debug=0[, dir=None[, makefile="Makefile"[, installs=None[, universal=None[, arch=None]]]]]]]]]]]]]]) + + :param configuration: + see :meth:`sipconfig.Makefile.__init__`. + :param build_file: + the name of the optional build file. Build files are generated + using the :option:`-b <sip -b>` SIP command line option. + :param install_dir: + the name of the directory where the executable program will be + optionally installed. + :param console: + see :meth:`sipconfig.Makefile.__init__`. + :param qt: + see :meth:`sipconfig.Makefile.__init__`. + :param opengl: + see :meth:`sipconfig.Makefile.__init__`. + :param python: + see :meth:`sipconfig.Makefile.__init__`. + :param threaded: + see :meth:`sipconfig.Makefile.__init__`. + :param warnings: + see :meth:`sipconfig.Makefile.__init__`. + :param debug: + see :meth:`sipconfig.Makefile.__init__`. + :param dir: + see :meth:`sipconfig.Makefile.__init__`. + :param makefile: + see :meth:`sipconfig.Makefile.__init__`. + :param installs: + see :meth:`sipconfig.Makefile.__init__`. + :param universal: + see :meth:`sipconfig.Makefile.__init__`. + :param arch: + see :meth:`sipconfig.Makefile.__init__`. + + .. method:: build_command(source) -> string, string + + This creates a single command line that will create an executable + program from a single source file. + + :param source: + the name of the source file. + :return: + a tuple of the name of the executable that will be created and the + command line. + + .. method:: finalise() + + This is a reimplementation of :meth:`sipconfig.Makefile.finalise`. + + .. method:: generate_macros_and_rules(mfile) + + This is a reimplementation of + :meth:`sipconfig.Makefile.generate_macros_and_rules`. + + .. method:: generate_target_clean(mfile) + + This is a reimplementation of + :meth:`sipconfig.Makefile.generate_target_clean`. + + .. method:: generate_target_default(mfile) + + This is a reimplementation of + :meth:`sipconfig.Makefile.generate_target_default`. + + .. method:: generate_target_install(mfile) + + This is a reimplementation of + :meth:`sipconfig.Makefile.generate_target_install`. + + +.. class:: PythonModuleMakefile + + This class is derived from :class:`sipconfig.Makefile`. + + This class encapsulates a Makefile that installs a pure Python module. + + .. method:: __init__(self, configuration, dstdir[, srcdir=None[, dir=None[, makefile="Makefile"[, installs=None]]]]) + + :param configuration: + see :meth:`sipconfig.Makefile.__init__`. + :param dstdir: + the name of the directory in which the module's Python code will be + installed. + :param srcdir: + the name of the directory (relative to *dir*) containing the + module's Python code. It defaults to the same directory. + :param dir: + see :meth:`sipconfig.Makefile.__init__`. + :param makefile: + see :meth:`sipconfig.Makefile.__init__`. + :param installs: + see :meth:`sipconfig.Makefile.__init__`. + + .. method:: generate_macros_and_rules(mfile) + + This is a reimplementation of + :meth:`sipconfig.Makefile.generate_macros_and_rules`. + + .. method:: generate_target_install(mfile) + + This is a reimplementation of + :meth:`sipconfig.Makefile.generate_target_install`. + + +.. class:: SIPModuleMakefile + + This class is derived from :class:`sipconfig.ModuleMakefile`. + + This class encapsulates a Makefile to build a SIP generated Python + extension module. + + .. method:: __init__(self, configuration, build_file[, install_dir=None[, static=0[, console=0[, opengl=0[, threaded=0[, warnings=None[, debug=0[, dir=None[, makefile="Makefile"[, installs=None[, strip=1[, export_all=0[, universal=None[, arch=None[, prot_is_public=0]]]]]]]]]]]]]]]) + + :param configuration: + see :meth:`sipconfig.Makefile.__init__`. + :param build_file: + see :meth:`sipconfig.ModuleMakefile.__init__`. + :param install_dir: + see :meth:`sipconfig.ModuleMakefile.__init__`. + :param static: + see :meth:`sipconfig.ModuleMakefile.__init__`. + :param console: + see :meth:`sipconfig.Makefile.__init__`. + :param qt: + see :meth:`sipconfig.Makefile.__init__`. + :param opengl: + see :meth:`sipconfig.Makefile.__init__`. + :param threaded: + see :meth:`sipconfig.Makefile.__init__`. + :param warnings: + see :meth:`sipconfig.Makefile.__init__`. + :param debug: + see :meth:`sipconfig.Makefile.__init__`. + :param dir: + see :meth:`sipconfig.Makefile.__init__`. + :param makefile: + see :meth:`sipconfig.Makefile.__init__`. + :param installs: + see :meth:`sipconfig.Makefile.__init__`. + :param strip: + see :meth:`sipconfig.ModuleMakefile.__init__`. + :param export_all: + see :meth:`sipconfig.ModuleMakefile.__init__`. + :param universal: + see :meth:`sipconfig.Makefile.__init__`. + :param arch: + see :meth:`sipconfig.Makefile.__init__`. + :param prot_is_public: + is set if ``protected`` should be redefined as ``public`` when + compiling the generated module. + + .. method:: finalise() + + This is a reimplementation of :meth:`sipconfig.Makefile.finalise`. diff --git a/sphinx/builtin.rst b/sphinx/builtin.rst new file mode 100644 index 0000000..58c7019 --- /dev/null +++ b/sphinx/builtin.rst @@ -0,0 +1,50 @@ +.. _ref-builtin: + +Builtin Modules and Custom Interpreters +======================================= + +Sometimes you want to create a custom Python interpreter with some modules +built in to the interpreter itself rather than being dynamically loaded. To +do this the module must be created as a static library and linked with a +custom stub and the normal Python library. + +To build the SIP module as a static library you must pass the ``-k`` command +line option to ``configure.py``. You should then build and install SIP as +normal. (Note that, because the module is now a static library, you will not +be able to import it.) + +To build a module you have created for your own library you must modify your +own configuration script to pass a non-zero value as the ``static`` argument +of the ``__init__()`` method of the :class:`sipconfig.ModuleMakefile` class (or +any derived class you have created). Normally you would make this configurable +using a command line option in the same way that SIP's ``configure.py`` handles +it. + +The next stage is to create a custom stub and a Makefile. The SIP distribution +contains a directory called ``custom`` which contains example stubs and a +Python script that will create a correct Makefile. Note that, if your copy of +SIP was part of a standard Linux distribution, the ``custom`` directory may +not be installed on your system. + +The ``custom`` directory contains the following files. They are provided as +examples - each needs to be modified according to your particular +requirements. + + - ``mkcustom.py`` is a Python script that will create a Makefile which is + then used to build the custom interpreter. Comments in the file describe + how it should be modified. + + - ``custom.c`` is a stub for a custom interpreter on Linux/UNIX. It + should also be used for a custom console interpreter on Windows (i.e. + like ``python.exe``). Comments in the file describe how it should be + modified. + + - ``customw.c`` is a stub for a custom GUI interpreter on Windows (i.e. + like ``pythonw.exe``). Comments in the file describe how it should be + modified. + +Note that this technique does not restrict how the interpreter can be used. +For example, it still allows users to write their own applications that can +import your builtin modules. If you want to prevent users from doing that, +perhaps to protect a proprietary API, then take a look at the +`VendorID <http://www.riverbankcomputing.com/software/vendorid/>`__ package. diff --git a/sphinx/c_api.rst b/sphinx/c_api.rst new file mode 100644 index 0000000..782056c --- /dev/null +++ b/sphinx/c_api.rst @@ -0,0 +1,1721 @@ +.. _ref-c-api: + +C API for Handwritten Code +========================== + +In this section we describe the API that can be used by handwritten code in +specification files. + + +.. cmacro:: SIP_API_MAJOR_NR + + This is a C preprocessor symbol that defines the major number of the SIP + API. Its value is a number. There is no direct relationship between this + and the SIP version number. + + +.. cmacro:: SIP_API_MINOR_NR + + This is a C preprocessor symbol that defines the minor number of the SIP + API. Its value is a number. There is no direct relationship between this + and the SIP version number. + + +.. cmacro:: SIP_BLOCK_THREADS + + This is a C preprocessor macro that will make sure the Python Global + Interpreter Lock (GIL) is acquired. Python API calls must only be made + when the GIL has been acquired. There must be a corresponding + :cmacro:`SIP_UNBLOCK_THREADS` at the same lexical scope. + + +.. cmacro:: SIP_NO_CONVERTORS + + This is a flag used by various type convertors that suppresses the use of a + type's :directive:`%ConvertToTypeCode`. + + +.. cmacro:: SIP_NOT_NONE + + This is a flag used by various type convertors that causes the conversion + to fail if the Python object being converted is ``Py_None``. + + +.. cmacro:: SIP_PROTECTED_IS_PUBLIC + + .. versionadded:: 4.10 + + This is a C preprocessor macro that is set automatically by the build + system to specify that the generated code is being compiled with + ``protected`` redefined as ``public``. This allows handwritten code to + determine if the generated helper functions for accessing protected C++ + functions are available (see :directive:`%MethodCode`). + + +.. cmacro:: SIP_SSIZE_T + + This is a C preprocessor macro that is defined as ``Py_ssize_t`` for Python + v2.5 and later, and as ``int`` for earlier versions of Python. It makes it + easier to write PEP 353 compliant handwritten code. + + +.. cmacro:: SIP_UNBLOCK_THREADS + + This is a C preprocessor macro that will restore the Python Global + Interpreter Lock (GIL) to the state it was prior to the corresponding + :cmacro:`SIP_BLOCK_THREADS`. + + +.. cmacro:: SIP_VERSION + + This is a C preprocessor symbol that defines the SIP version number + represented as a 3 part hexadecimal number (e.g. v4.0.0 is represented as + ``0x040000``). + + +.. cmacro:: SIP_VERSION_STR + + This is a C preprocessor symbol that defines the SIP version number + represented as a string. For development snapshots it will start with + ``snapshot-``. + + +.. cfunction:: sipErrorState sipBadCallableArg(int arg_nr, PyObject *arg) + + .. versionadded:: 4.10 + + This is called from :directive:`%MethodCode` to raise a Python exception + when an argument to a function, a C++ constructor or method is found to + have an unexpected type. This should be used when the + :directive:`%MethodCode` does additional type checking of the supplied + arguments. + + :param arg_nr: + the number of the argument. Arguments are numbered from 0 but are + numbered from 1 in the detail of the exception. + :param arg: + the argument. + :return: + the value that should be assigned to ``sipError``. + + +.. cfunction:: void sipBadCatcherResult(PyObject *method) + + This raises a Python exception when the result of a Python reimplementation + of a C++ method doesn't have the expected type. It is normally called by + handwritten code specified with the :directive:`%VirtualCatcherCode` + directive. + + :param method: + the Python method and would normally be the supplied ``sipMethod``. + + +.. cfunction:: void sipBadLengthForSlice(SIP_SSIZE_T seqlen, SIP_SSIZE_T slicelen) + + This raises a Python exception when the length of a slice object is + inappropriate for a sequence-like object. It is normally called by + handwritten code specified for :meth:`__setitem__` methods. + + :param seqlen: + the length of the sequence. + :param slicelen: + the length of the slice. + + +.. cfunction:: PyObject *sipBuildResult(int *iserr, const char *format, ...) + + This creates a Python object based on a format string and associated + values in a similar way to the Python :cfunc:`Py_BuildValue()` function. + + :param iserr: + if this is not ``NULL`` then the location it points to is set to a + non-zero value. + :param format: + the string of format characters. + :return: + If there was an error then ``NULL`` is returned and a Python exception + is raised. + + If the format string begins and ends with parentheses then a tuple of + objects is created. If it contains more than one format character then + parentheses must be specified. + + In the following description the first letter is the format character, the + entry in parentheses is the Python object type that the format character + will create, and the entry in brackets are the types of the C/C++ values + to be passed. + + ``a`` (string) [char] + Convert a C/C++ ``char`` to a Python v2 or v3 string object. + + ``b`` (boolean) [int] + Convert a C/C++ ``int`` to a Python boolean. + + ``c`` (string/bytes) [char] + Convert a C/C++ ``char`` to a Python v2 string object or a Python v3 + bytes object. + + ``d`` (float) [double] + Convert a C/C++ ``double`` to a Python floating point number. + + ``e`` (integer) [enum] + Convert an anonymous C/C++ ``enum`` to a Python integer. + + ``f`` (float) [float] + Convert a C/C++ ``float`` to a Python floating point number. + + ``g`` (string/bytes) [char \*, :cmacro:`SIP_SSIZE_T`] + Convert a C/C++ character array and its length to a Python v2 string + object or a Python v3 bytes object. If the array is ``NULL`` then the + length is ignored and the result is ``Py_None``. + + ``h`` (integer) [short] + Convert a C/C++ ``short`` to a Python integer. + + ``i`` (integer) [int] + Convert a C/C++ ``int`` to a Python integer. + + ``l`` (long) [long] + Convert a C/C++ ``long`` to a Python integer. + + ``m`` (long) [unsigned long] + Convert a C/C++ ``unsigned long`` to a Python long. + + ``n`` (long) [long long] + Convert a C/C++ ``long long`` to a Python long. + + ``o`` (long) [unsigned long long] + Convert a C/C++ ``unsigned long long`` to a Python long. + + ``r`` (wrapped instance) [*type* \*, :cmacro:`SIP_SSIZE_T`, const :ctype:`sipTypeDef` \*] + Convert an array of C structures, C++ classes or mapped type instances + to a Python tuple. Note that copies of the array elements are made. + + ``s`` (string/bytes) [char \*] + Convert a C/C++ ``'\0'`` terminated string to a Python v2 string object + or a Python v3 bytes object. If the string pointer is ``NULL`` then + the result is ``Py_None``. + + ``t`` (long) [unsigned short] + Convert a C/C++ ``unsigned short`` to a Python long. + + ``u`` (long) [unsigned int] + Convert a C/C++ ``unsigned int`` to a Python long. + + ``w`` (unicode/string) [wchar_t] + Convert a C/C++ wide character to a Python v2 unicode object or a + Python v3 string object. + + ``x`` (unicode/string) [wchar_t \*] + Convert a C/C++ ``L'\0'`` terminated wide character string to a Python + v2 unicode object or a Python v3 string object. If the string pointer + is ``NULL`` then the result is ``Py_None``. + + ``A`` (string) [char \*] + Convert a C/C++ ``'\0'`` terminated string to a Python v2 or v3 string + object. If the string pointer is ``NULL`` then the result is + ``Py_None``. + + ``B`` (wrapped instance) [*type* \*, :ctype:`sipWrapperType` \*, PyObject \*] + Convert a new C structure or a new C++ class instance to a Python class + instance object. Ownership of the structure or instance is determined + by the ``PyObject *`` argument. If it is ``NULL`` and the instance has + already been wrapped then the ownership is unchanged. If it is + ``NULL`` or ``Py_None`` then ownership will be with Python. Otherwise + ownership will be with C/C++ and the instance associated with the + ``PyObject *`` argument. The Python class is influenced by any + applicable :directive:`%ConvertToSubClassCode` code. + + .. note:: + This is deprecated from SIP v4.8. Instead you should use ``N``. + + ``C`` (wrapped instance) [*type* \*, :ctype:`sipWrapperType` \*, PyObject \*] + Convert a C structure or a C++ class instance to a Python class + instance object. If the structure or class instance has already been + wrapped then the result is a new reference to the existing class + instance object. Ownership of the structure or instance is determined + by the ``PyObject *`` argument. If it is ``NULL`` and the instance has + already been wrapped then the ownership is unchanged. If it is + ``NULL`` and the instance is newly wrapped then ownership will be with + C/C++. If it is ``Py_None`` then ownership is transferred to Python + via a call to :cfunc:`sipTransferBack()`. Otherwise ownership is + transferred to C/C++ and the instance associated with the + ``PyObject *`` argument via a call to :cfunc:`sipTransferTo()`. The + Python class is influenced by any applicable + :directive:`%ConvertToSubClassCode` code. + + .. note:: + This is deprecated from SIP v4.8. Instead you should use ``D``. + + ``D`` (wrapped instance) [*type* \*, const :ctype:`sipTypeDef` \*, PyObject \*] + Convert a C structure, C++ class or mapped type instance to a Python + object. If the instance has already been wrapped then the result is a + new reference to the existing object. Ownership of the instance is + determined by the ``PyObject *`` argument. If it is ``NULL`` and the + instance has already been wrapped then the ownership is unchanged. If + it is ``NULL`` and the instance is newly wrapped then ownership will be + with C/C++. If it is ``Py_None`` then ownership is transferred to + Python via a call to :cfunc:`sipTransferBack()`. Otherwise ownership + is transferred to C/C++ and the instance associated with the + ``PyObject *`` argument via a call to :cfunc:`sipTransferTo()`. The + Python class is influenced by any applicable + :directive:`%ConvertToSubClassCode` code. + + ``E`` (wrapped enum) [enum, PyTypeObject \*] + Convert a named C/C++ ``enum`` to an instance of the corresponding + Python named enum type. + + .. note:: + This is deprecated from SIP v4.8. Instead you should use ``F``. + + ``F`` (wrapped enum) [enum, :ctype:`sipTypeDef` \*] + Convert a named C/C++ ``enum`` to an instance of the corresponding + Python named enum type. + + ``G`` (unicode) [wchar_t \*, :cmacro:`SIP_SSIZE_T`] + Convert a C/C++ wide character array and its length to a Python unicode + object. If the array is ``NULL`` then the length is ignored and the + result is ``Py_None``. + + ``N`` (wrapped instance) [*type* \*, :ctype:`sipTypeDef` \*, PyObject \*] + Convert a new C structure, C++ class or mapped type instance to a + Python object. Ownership of the instance is determined by the + ``PyObject *`` argument. If it is ``NULL`` and the instance has + already been wrapped then the ownership is unchanged. If it is + ``NULL`` or ``Py_None`` then ownership will be with Python. Otherwise + ownership will be with C/C++ and the instance associated with the + ``PyObject *`` argument. The Python class is influenced by any + applicable :directive:`%ConvertToSubClassCode` code. + + ``R`` (object) [PyObject \*] + The result is value passed without any conversions. The reference + count is unaffected, i.e. a reference is taken. + + ``S`` (object) [PyObject \*] + The result is value passed without any conversions. The reference + count is incremented. + + ``V`` (sip.voidptr) [void \*] + Convert a C/C++ ``void *`` Python :class:`sip.voidptr` object. + + +.. cfunction:: PyObject *sipCallMethod(int *iserr, PyObject *method, const char *format, ...) + + This calls a Python method passing a tuple of arguments based on a format + string and associated values in a similar way to the Python + :cfunc:`PyObject_CallObject()` function. + + :param iserr: + if this is not ``NULL`` then the location it points to is set to a + non-zero value if there was an error. + :param method: + the Python bound method to call. + :param format: + the string of format characters (see :cfunc:`sipBuildResult()`). + :return: + If there was an error then ``NULL`` is returned and a Python exception + is raised. + + It is normally called by handwritten code specified with the + :directive:`%VirtualCatcherCode` directive with method being the supplied + ``sipMethod``. + + +.. cfunction:: int sipCanConvertToEnum(PyObject *obj, const sipTypeDef *td) + + This checks if a Python object can be converted to a named enum. + + :param obj: + the Python object. + :param td: + the enum's :ref:`generated type structure <ref-type-structures>`. + :return: + a non-zero value if the object can be converted. + + +.. cfunction:: int sipCanConvertToInstance(PyObject *obj, sipWrapperType *type, int flags) + + This checks if a Python object can be converted to an instance of a C + structure or C++ class. + + :param obj: + the Python object. + :param type: + the C/C++ type's :ref:`generated type object <ref-type-objects>`. + :param flags: + any combination of the :cmacro:`SIP_NOT_NONE` and + :cmacro:`SIP_NO_CONVERTORS` flags. + :return: + a non-zero value if the object can be converted. + + .. note:: + This is deprecated from SIP v4.8. Instead you should use + :cfunc:`sipCanConvertToType()`. + + +.. cfunction:: int sipCanConvertToMappedType(PyObject *obj, const sipMappedType *mt, int flags) + + This checks if a Python object can be converted to an instance of a C + structure or C++ class which has been implemented as a mapped type. + + :param obj: + the Python object. + :param mt: + the opaque structure returned by :cfunc:`sipFindMappedType()`. + :param flags: + this may be the :cmacro:`SIP_NOT_NONE` flag. + :return: + a non-zero value if the object can be converted. + + .. note:: + This is deprecated from SIP v4.8. Instead you should use + :cfunc:`sipCanConvertToType()`. + + +.. cfunction:: int sipCanConvertToType(PyObject *obj, const sipTypeDef *td, int flags) + + This checks if a Python object can be converted to an instance of a C + structure, C++ class or mapped type. + + :param obj: + the Python object. + :param td: + the C/C++ type's :ref:`generated type structure <ref-type-structures>`. + :param flags: + any combination of the :cmacro:`SIP_NOT_NONE` and + :cmacro:`SIP_NO_CONVERTORS` flags. + :return: + a non-zero value if the object can be converted. + + +.. cfunction:: PyObject *sipClassName(PyObject *obj) + + This gets the class name of a wrapped instance as a Python string. It + comes with a reference. + + :param obj: + the wrapped instance. + :return: + the name of the instance's class. + + .. note:: + This is deprecated from SIP v4.8. Instead you should use the + following:: + + PyString_FromString(obj->ob_type->tp_name) + + +.. cfunction:: PyObject *sipConvertFromConstVoidPtr(const void *cpp) + + This creates a :class:`sip.voidptr` object for a memory address. The + object will not be writeable and has no associated size. + + :param cpp: + the memory address. + :return: + the :class:`sip.voidptr` object. + + +.. cfunction:: PyObject *sipConvertFromConstVoidPtrAndSize(const void *cpp, SIP_SSIZE_T size) + + This creates a :class:`sip.voidptr` object for a memory address. The + object will not be writeable and can be used as an immutable buffer object. + + :param cpp: + the memory address. + :param size: + the size associated with the address. + :return: + the :class:`sip.voidptr` object. + + +.. cfunction:: PyObject *sipConvertFromEnum(int eval, const sipTypeDef *td) + + This converts a named C/C++ ``enum`` to an instance of the corresponding + generated Python type. + + :param eval: + the enumerated value to convert. + :param td: + the enum's :ref:`generated type structure <ref-type-structures>`. + :return: + the Python object. + + +.. cfunction:: PyObject *sipConvertFromInstance(void *cpp, sipWrapperType *type, PyObject *transferObj) + + This converts a C structure or a C++ class instance to an instance of the + corresponding generated Python type. + + :param cpp: + the C/C++ instance. + :param type: + the type's :ref:`generated type object <ref-type-objects>`. + :param transferObj: + this controls the ownership of the returned value. + :return: + the Python object. + + If the C/C++ instance has already been wrapped then the result is a + new reference to the existing class instance object. + + If *transferObj* is ``NULL`` and the instance has already been wrapped then + the ownership is unchanged. + + If *transferObj* is ``NULL`` and the instance is newly wrapped then + ownership will be with C/C++. + + If *transferObj* is ``Py_None`` then ownership is transferred to Python via + a call to :cfunc:`sipTransferBack()`. + + Otherwise ownership is transferred to C/C++ and the instance associated + with *transferObj* via a call to :cfunc:`sipTransferTo()`. + + The Python type is influenced by any applicable + :directive:`%ConvertToSubClassCode` code. + + .. note:: + This is deprecated from SIP v4.8. Instead you should use + :cfunc:`sipConvertFromType()`. + + +.. cfunction:: PyObject *sipConvertFromMappedType(void *cpp, const sipMappedType *mt, PyObject *transferObj) + + This converts a C structure or a C++ class instance wrapped as a mapped + type to an instance of the corresponding generated Python type. + + :param cpp: + the C/C++ instance. + :param mt: + the opaque structure returned by :cfunc:`sipFindMappedType()`. + :param transferObj: + this controls the ownership of the returned value. + :return: + the Python object. + + If *transferObj* is ``NULL`` then the ownership is unchanged. + + If *transferObj* is ``Py_None`` then ownership is transferred to Python + via a call to :cfunc:`sipTransferBack()`. + + Otherwise ownership is transferred to C/C++ and the instance associated + with *transferObj* argument via a call to :cfunc:`sipTransferTo()`. + + .. note:: + This is deprecated from SIP v4.8. Instead you should use + :cfunc:`sipConvertFromType()`. + + +.. cfunction:: PyObject *sipConvertFromNamedEnum(int eval, PyTypeObject *type) + + This converts a named C/C++ ``enum`` to an instance of the corresponding + generated Python type. + + :param eval: + the enumerated value to convert. + :param type: + the enum's :ref:`generated type object <ref-type-objects>`. + :return: + the Python object. + + .. note:: + This is deprecated from SIP v4.8. Instead you should use + :cfunc:`sipConvertFromEnum()`. + + +.. cfunction:: PyObject *sipConvertFromNewInstance(void *cpp, sipWrapperType *type, PyObject *transferObj) + + This converts a new C structure or a C++ class instance to an instance of + the corresponding generated Python type. + + :param cpp: + the C/C++ instance. + :param type: + the type's :ref:`generated type object <ref-type-objects>`. + :param transferObj: + this controls the ownership of the returned value. + :return: + the Python object. + + If *transferObj* is ``NULL`` or ``Py_None`` then ownership will be with + Python. + + Otherwise ownership will be with C/C++ and the instance associated with + *transferObj*. + + The Python type is influenced by any applicable + :directive:`%ConvertToSubClassCode` code. + + .. note:: + This is deprecated from SIP v4.8. Instead you should use + :cfunc:`sipConvertFromNewType()`. + + +.. cfunction:: PyObject *sipConvertFromNewType(void *cpp, const sipTypeDef *td, PyObject *transferObj) + + This converts a new C structure or a C++ class instance to an instance of + the corresponding generated Python type. + + :param cpp: + the C/C++ instance. + :param td: + the type's :ref:`generated type structure <ref-type-structures>`. + :param transferObj: + this controls the ownership of the returned value. + :return: + the Python object. + + If *transferObj* is ``NULL`` or ``Py_None`` then ownership will be with + Python. + + Otherwise ownership will be with C/C++ and the instance associated with + *transferObj*. + + The Python type is influenced by any applicable + :directive:`%ConvertToSubClassCode` code. + + +.. cfunction:: SIP_SSIZE_T sipConvertFromSequenceIndex(SIP_SSIZE_T idx, SIP_SSIZE_T len) + + This converts a Python sequence index (i.e. where a negative value refers + to the offset from the end of the sequence) to a C/C++ array index. If the + index was out of range then a negative value is returned and a Python + exception raised. + + :param idx: + the sequence index. + :param len: + the length of the sequence. + :return: + the unsigned array index. + + +.. cfunction:: int sipConvertFromSliceObject(PyObject *slice, SIP_SSIZE_T length, SIP_SSIZE_T *start, SIP_SSIZE_T *stop, SIP_SSIZE_T *step, SIP_SSIZE_T *slicelength) + + This is a thin wrapper around the Python :cfunc:`PySlice_GetIndicesEx()` + function provided to make it easier to write handwritten code that is + compatible with SIP v3.x and versions of Python earlier that v2.3. + + +.. cfunction:: PyObject *sipConvertFromType(void *cpp, const sipTypeDef *td, PyObject *transferObj) + + This converts a C structure or a C++ class instance to an instance of the + corresponding generated Python type. + + :param cpp: + the C/C++ instance. + :param td: + the type's :ref:`generated type structure <ref-type-structures>`. + :param transferObj: + this controls the ownership of the returned value. + :return: + the Python object. + + If the C/C++ instance has already been wrapped then the result is a new + reference to the existing object. + + If *transferObj* is ``NULL`` and the instance has already been wrapped then + the ownership is unchanged. + + If *transferObj* is ``NULL`` and the instance is newly wrapped then + ownership will be with C/C++. + + If *transferObj* is ``Py_None`` then ownership is transferred to Python via + a call to :cfunc:`sipTransferBack()`. + + Otherwise ownership is transferred to C/C++ and the instance associated + with *transferObj* via a call to :cfunc:`sipTransferTo()`. + + The Python class is influenced by any applicable + :directive:`%ConvertToSubClassCode` code. + + +.. cfunction:: PyObject *sipConvertFromVoidPtr(void *cpp) + + This creates a :class:`sip.voidptr` object for a memory address. The + object will be writeable but has no associated size. + + :param cpp: + the memory address. + :return: + the :class:`sip.voidptr` object. + + +.. cfunction:: PyObject *sipConvertFromVoidPtrAndSize(void *cpp, SIP_SSIZE_T size) + + This creates a :class:`sip.voidptr` object for a memory address. The + object will be writeable and can be used as a mutable buffer object. + + :param cpp: + the memory address. + :param size: + the size associated with the address. + :return: + the :class:`sip.voidptr` object. + + +.. cfunction:: void *sipConvertToInstance(PyObject *obj, sipWrapperType *type, PyObject *transferObj, int flags, int *state, int *iserr) + + This converts a Python object to an instance of a C structure or C++ class + assuming that a previous call to :cfunc:`sipCanConvertToInstance()` has + been successful. + + :param obj: + the Python object. + :param type: + the type's :ref:`generated type object <ref-type-objects>`. + :param transferObj: + this controls any ownership changes to *obj*. + :param flags: + any combination of the :cmacro:`SIP_NOT_NONE` and + :cmacro:`SIP_NO_CONVERTORS` flags. + :param state: + the state of the returned C/C++ instance is returned via this pointer. + :param iserr: + the error flag is passed and updated via this pointer. + :return: + the C/C++ instance. + + If *transferObj* is ``NULL`` then the ownership is unchanged. + + If *transferObj* is ``Py_None`` then ownership is transferred to Python via + a call to :cfunc:`sipTransferBack()`. + + Otherwise ownership is transferred to C/C++ and *obj* associated with + *transferObj* via a call to :cfunc:`sipTransferTo()`. + + If *state* is not ``NULL`` then the location it points to is set to + describe the state of the returned C/C++ instance and is the value returned + by any :directive:`%ConvertToTypeCode`. The calling code must then release + the value at some point to prevent a memory leak by calling + :cfunc:`sipReleaseInstance()`. + + If there is an error then the location *iserr* points to is set to a + non-zero value. If it was initially a non-zero value then the conversion + isn't attempted in the first place. (This allows several calls to be made + that share the same error flag so that it only needs to be tested once + rather than after each call.) + + .. note:: + This is deprecated from SIP v4.8. Instead you should use + :cfunc:`sipConvertToType()`. + + +.. cfunction:: void *sipConvertToMappedType(PyObject *obj, const sipMappedType *mt, PyObject *transferObj, int flags, int *state, int *iserr) + + This converts a Python object to an instance of a C structure or C++ + class that is implemented as a mapped type assuming that a previous call to + :cfunc:`sipCanConvertToMappedType()` has been successful. + + :param obj: + the Python object. + :param mt: + the opaque structure returned by :cfunc:`sipFindMappedType()`. + :param transferObj: + this controls any ownership changes to *obj*. + :param flags: + this may be the :cmacro:`SIP_NOT_NONE` flag. + :param state: + the state of the returned C/C++ instance is returned via this pointer. + :param iserr: + the error flag is passed and updated via this pointer. + :return: + the C/C++ instance. + + If *transferObj* is ``NULL`` then the ownership is unchanged. + + If *transferObj* is ``Py_None`` then ownership is transferred to Python via + a call to :cfunc:`sipTransferBack()`. + + Otherwise ownership is transferred to C/C++ and *obj* associated with + *transferObj* via a call to :cfunc:`sipTransferTo()`. + + If *state* is not ``NULL`` then the location it points to is set to + describe the state of the returned C/C++ instance and is the value returned + by any :directive:`%ConvertToTypeCode`. The calling code must then release + the value at some point to prevent a memory leak by calling + :cfunc:`sipReleaseMappedType()`. + + If there is an error then the location *iserr* points to is set to a + non-zero value. If it was initially a non-zero value then the conversion + isn't attempted in the first place. (This allows several calls to be made + that share the same error flag so that it only needs to be tested once + rather than after each call.) + + .. note:: + This is deprecated from SIP v4.8. Instead you should use + :cfunc:`sipConvertToType()` + + +.. cfunction:: void *sipConvertToType(PyObject *obj, const sipTypeDef *td, PyObject *transferObj, int flags, int *state, int *iserr) + + This converts a Python object to an instance of a C structure, C++ class or + mapped type assuming that a previous call to :cfunc:`sipCanConvertToType()` + has been successful. + + :param obj: + the Python object. + :param td: + the type's :ref:`generated type structure <ref-type-structures>`. + :param transferObj: + this controls any ownership changes to *obj*. + :param flags: + any combination of the :cmacro:`SIP_NOT_NONE` and + :cmacro:`SIP_NO_CONVERTORS` flags. + :param state: + the state of the returned C/C++ instance is returned via this pointer. + :param iserr: + the error flag is passed and updated via this pointer. + :return: + the C/C++ instance. + + If *transferObj* is ``NULL`` then the ownership is unchanged. If it is + ``Py_None`` then ownership is transferred to Python via a call to + :cfunc:`sipTransferBack()`. + + Otherwise ownership is transferred to C/C++ and *obj* associated with + *transferObj* via a call to :cfunc:`sipTransferTo()`. + + If *state* is not ``NULL`` then the location it points to is set to + describe the state of the returned C/C++ instance and is the value returned + by any :directive:`%ConvertToTypeCode`. The calling code must then release + the value at some point to prevent a memory leak by calling + :cfunc:`sipReleaseType()`. + + If there is an error then the location *iserr* points to is set to a + non-zero value. If it was initially a non-zero value then the conversion + isn't attempted in the first place. (This allows several calls to be made + that share the same error flag so that it only needs to be tested once + rather than after each call.) + + +.. cfunction:: void *sipConvertToVoidPtr(PyObject *obj) + + This converts a Python object to a memory address. + :cfunc:`PyErr_Occurred()` must be used to determine if the conversion was + successful. + + :param obj: + the Python object which may be ``Py_None``, a :class:`sip.voidptr` or a + :ctype:`PyCObject`. + :return: + the memory address. + + +.. cfunction:: int sipExportSymbol(const char *name, void *sym) + + Python does not allow extension modules to directly access symbols in + another extension module. This exports a symbol, referenced by a name, + that can subsequently be imported, using :cfunc:`sipImportSymbol()`, by + another module. + + :param name: + the name of the symbol. + :param sym: + the value of the symbol. + :return: + 0 if there was no error. A negative value is returned if *name* is + already associated with a symbol or there was some other error. + + +.. cfunction:: sipWrapperType *sipFindClass(const char *type) + + This returns a pointer to the :ref:`generated type object + <ref-type-objects` corresponding to a C/C++ type. + + :param type: + the C/C++ declaration of the type. + :return: + the generated type object. This will not change and may be saved in a + static cache. ``NULL`` is returned if the C/C++ type doesn't exist. + + .. note:: + This is deprecated from SIP v4.8. Instead you should use + :cfunc:`sipFindType()`. + + +.. cfunction:: const sipMappedType *sipFindMappedType(const char *type) + + This returns a pointer to an opaque structure describing a mapped type. + + :param type: + the C/C++ declaration of the type. + :return: + the opaque structure. This will not change and may be saved in a + static cache. ``NULL`` is returned if the C/C++ type doesn't exist. + + .. note:: + This is deprecated from SIP v4.8. Instead you should use + :cfunc:`sipFindType()`. + + +.. cfunction:: PyTypeObject *sipFindNamedEnum(const char *type) + + This returns a pointer to the :ref:`generated Python type object + <ref-enum-type-objects>` corresponding to a named C/C++ enum. + + :param type: + the C/C++ declaration of the enum. + :return: + the generated Python type object. This will not change and may be + saved in a static cache. ``NULL`` is returned if the C/C++ enum + doesn't exist. + + .. note:: + This is deprecated from SIP v4.8. Instead you should use + :cfunc:`sipFindType()`. + + +.. cfunction:: const sipTypeDef *sipFindType(const char *type) + + This returns a pointer to the :ref:`generated type structure + <ref-type-structures>` corresponding to a C/C++ type. + + :param type: + the C/C++ declaration of the type. + :return: + the generated type structure. This will not change and may be saved in + a static cache. ``NULL`` is returned if the C/C++ type doesn't exist. + + +.. cfunction:: void *sipForceConvertToInstance(PyObject *obj, sipWrapperType *type, PyObject *transferObj, int flags, int *state, int *iserr) + + This converts a Python object to an instance of a C structure or C++ class + by calling :cfunc:`sipCanConvertToInstance()` and, if it is successfull, + calling :cfunc:`sipConvertToInstance()`. + + See :cfunc:`sipConvertToInstance()` for a full description of the + arguments. + + .. note:: + This is deprecated from SIP v4.8. Instead you should use + :cfunc:`sipForceConvertToType()`. + + +.. cfunction:: void *sipForceConvertToMappedType(PyObject *obj, const sipMappedType *mt, PyObject *transferObj, int flags, int *state, int *iserr) + + This converts a Python object to an instance of a C structure or C++ class + which has been implemented as a mapped type by calling + :cfunc:`sipCanConvertToMappedType()` and, if it is successfull, calling + :cfunc:`sipConvertToMappedType()`. + + See :cfunc:`sipConvertToMappedType()` for a full description of the + arguments. + + .. note:: + This is deprecated from SIP v4.8. Instead you should use + :cfunc:`sipForceConvertToType()`. + + +.. cfunction:: void *sipForceConvertToType(PyObject *obj, const sipTypeDef *td, PyObject *transferObj, int flags, int *state, int *iserr) + + This converts a Python object to an instance of a C structure, C++ class or + mapped type by calling :cfunc:`sipCanConvertToType()` and, if it is + successfull, calling :cfunc:`sipConvertToType()`. + + See :cfunc:`sipConvertToType()` for a full description of the arguments. + + +.. cfunction:: void sipFree(void *mem) + + This returns an area of memory allocated by :cfunc:`sipMalloc()` to the + heap. + + :param mem: + the memory address. + + +.. cfunction:: PyObject *sipGetPyObject(void *cppptr, const sipTypeDef *td) + + This returns a borrowed reference to the Python object for a C structure or + C++ class instance. + + :param cppptr: + the pointer to the C/C++ instance. + :param td: + the :ref:`generated type structure <ref-type-structures>` corresponding + to the C/C++ type. + :return: + the Python object or ``NULL`` (and no exception is raised) if the + C/C++ instance hasn't been wrapped. + + +.. cfunction:: int sipGetState(PyObject *transferObj) + + The :directive:`%ConvertToTypeCode` directive requires that the provided + code returns an ``int`` describing the state of the converted value. The + state usually depends on any transfers of ownership that have been + requested. This is a convenience function that returns the correct state + when the converted value is a temporary. + + :param transferObj: + the object that describes the requested transfer of ownership. + :return: + the state of the converted value. + + +.. cfunction:: PyObject *sipGetWrapper(void *cppptr, sipWrapperType *type) + + This returns a borrowed reference to the wrapped instance object for a C + structure or C++ class instance. + + :param cppptr: + the pointer to the C/C++ instance. + :param type: + the :ref:`generated type object <ref-type-objects>` corresponding to + the C/C++ type. + :return: + the Python object or ``NULL`` (and no exception is raised) if the + C/C++ instance hasn't been wrapped. + + .. note:: + This is deprecated from SIP v4.8. Instead you should use + :cfunc:`sipGetPyObject()`. + + +.. cfunction:: void *sipImportSymbol(const char *name) + + Python does not allow extension modules to directly access symbols in + another extension module. This imports a symbol, referenced by a name, + that has previously been exported, using :cfunc:`sipExportSymbol()`, by + another module. + + :param name: + the name of the symbol. + :return: + the value of the symbol. ``NULL`` is returned if there is no such + symbol. + + +.. ctype:: sipIntTypeClassMap + + This C structure is used with :cfunc:`sipMapIntToClass()` to define a + mapping between integer based RTTI and :ref:`generated type objects + <ref-type-objects>`. The structure elements are as follows. + + .. cmember:: int typeInt + + The integer RTTI. + + .. cmember:: sipWrapperType **pyType. + + A pointer to the corresponding generated type object. + + .. note:: + This is deprecated from SIP v4.8. + + +.. cfunction:: int sipIsAPIEnabled(const char *name, int from, int to) + + .. versionadded:: 4.9 + + This checks to see if the current version number of an API falls within a + given range. See :ref:`ref-incompat-apis` for more detail. + + :param name: + the name of the API. + :param from: + the lower bound of the range. For the API to be enabled its version + number must be greater than or equal to *from*. If *from* is 0 then + this check isn't made. + :param to: + the upper bound of the range. For the API to be enabled its version + number must be less than *to*. If *to* is 0 then this check isn't + made. + :return: + a non-zero value if the API is enabled. + + +.. cfunction:: unsigned long sipLong_AsUnsignedLong(PyObject *obj) + + This function is a thin wrapper around :cfunc:`PyLong_AsUnsignedLong()` + that works around a bug in Python v2.3.x and earlier when converting + integer objects. + + +.. cfunction:: void *sipMalloc(size_t nbytes) + + This allocates an area of memory on the heap using the Python + :cfunc:`PyMem_Malloc()` function. The memory is freed by calling + :cfunc:`sipFree()`. + + :param nbytes: + the number of bytes to allocate. + :return: + the memory address. If there was an error then ``NULL`` is returned + and a Python exception raised. + + +.. cfunction:: sipWrapperType *sipMapIntToClass(int type, const sipIntTypeClassMap *map, int maplen) + + This can be used in :directive:`%ConvertToSubClassCode` code as a + convenient way of converting integer based RTTI to the corresponding + :ref:`generated type object <ref-type-objects>`. + + :param type: + the integer RTTI. + :param map: + the table of known RTTI and the corresponding type objects (see + :ctype:`sipIntTypeClassMap`). The entries in the table must be sorted + in ascending order of RTTI. + :param maplen: + the number of entries in the table. + :return: + the corresponding type object, or ``NULL`` if *type* wasn't in *map*. + + .. note:: + This is deprecated from SIP v4.8. + + +.. cfunction:: sipWrapperType *sipMapStringToClass(char *type, const sipStringTypeClassMap *map, int maplen) + + This can be used in :directive:`%ConvertToSubClassCode` code as a + convenient way of converting ``'\0'`` terminated string based RTTI to the + corresponding :ref:`generated type object <ref-type-objects>`. + + :param type: + the string RTTI. + :param map: + the table of known RTTI and the corresponding type objects (see + :ctype:`sipStringTypeClassMap`). The entries in the table must be + sorted in ascending order of RTTI. + :param maplen: + the number of entries in the table. + :return: + the corresponding type object, or ``NULL`` if *type* wasn't in *map*. + + .. note:: + This is deprecated from SIP v4.8. + + +.. cfunction:: int sipParseResult(int *iserr, PyObject *method, PyObject *result, const char *format, ...) + + This converts a Python object (usually returned by a method) to C/C++ based + on a format string and associated values in a similar way to the Python + :cfunc:`PyArg_ParseTuple()` function. + + :param iserr: + if this is not ``NULL`` then the location it points to is set to a + non-zero value if there was an error. + :param method: + the Python method that returned *result*. + :param result: + the Python object returned by *method*. + :param format: + the format string. + :return: + 0 if there was no error. Otherwise a negative value is returned, and + an exception raised. + + This is normally called by handwritten code specified with the + :directive:`%VirtualCatcherCode` directive with *method* being the supplied + ``sipMethod`` and *result* being the value returned by + :cfunc:`sipCallMethod()`. + + If *format* begins and ends with parentheses then *result* must be a Python + tuple and the rest of *format* is applied to the tuple contents. + + In the following description the first letter is the format character, the + entry in parentheses is the Python object type that the format character + will convert, and the entry in brackets are the types of the C/C++ values + to be passed. + + ``ae`` (object) [char \*] + Convert a Python string-like object of length 1 to a C/C++ ``char`` + according to the encoding ``e``. ``e`` can either be ``A`` for ASCII, + ``L`` for Latin-1, or ``8`` for UTF-8. For Python v2 the object may be + either a string or a unicode object that can be encoded. For Python v3 + the object may either be a bytes object or a string object that can be + encoded. An object that supports the buffer protocol may also be used. + + ``b`` (integer) [bool \*] + Convert a Python integer to a C/C++ ``bool``. + + ``c`` (string/bytes) [char \*] + Convert a Python v2 string object or a Python v3 bytes object of length + 1 to a C/C++ ``char``. + + ``d`` (float) [double \*] + Convert a Python floating point number to a C/C++ ``double``. + + ``e`` (integer) [enum \*] + Convert a Python integer to an anonymous C/C++ ``enum``. + + ``f`` (float) [float \*] + Convert a Python floating point number to a C/C++ ``float``. + + ``g`` (string/bytes) [const char \*\*, :cmacro:`SIP_SSIZE_T` \*] + Convert a Python v2 string object or a Python v3 bytes object to a + C/C++ character array and its length. If the Python object is + ``Py_None`` then the array and length are ``NULL`` and zero + respectively. + + ``h`` (integer) [short \*] + Convert a Python integer to a C/C++ ``short``. + + ``i`` (integer) [int \*] + Convert a Python integer to a C/C++ ``int``. + + ``l`` (long) [long \*] + Convert a Python long to a C/C++ ``long``. + + ``m`` (long) [unsigned long \*] + Convert a Python long to a C/C++ ``unsigned long``. + + ``n`` (long) [long long \*] + Convert a Python long to a C/C++ ``long long``. + + ``o`` (long) [unsigned long long \*] + Convert a Python long to a C/C++ ``unsigned long long``. + + ``s`` (string/bytes) [const char \*\*] + Convert a Python v2 string object or a Python v3 bytes object to a + C/C++ ``'\0'`` terminated string. If the Python object is ``Py_None`` + then the string is ``NULL``. + + .. note:: + This is deprecated from SIP v4.8. Instead you should use ``B``. + + ``t`` (long) [unsigned short \*] + Convert a Python long to a C/C++ ``unsigned short``. + + ``u`` (long) [unsigned int \*] + Convert a Python long to a C/C++ ``unsigned int``. + + ``w`` (unicode/string) [wchar_t \*] + Convert a Python v2 string or unicode object or a Python v3 string + object of length 1 to a C/C++ wide character. + + ``x`` (unicode/string) [wchar_t \*\*] + Convert a Python v2 string or unicode object or a Python v3 string + object to a C/C++ ``L'\0'`` terminated wide character string. If the + Python object is ``Py_None`` then the string is ``NULL``. + + ``Ae`` (object) [int, const char \*\*] + Convert a Python string-like object to a C/C++ ``'\0'`` terminated + string according to the encoding ``e``. ``e`` can either be ``A`` for + ASCII, ``L`` for Latin-1, or ``8`` for UTF-8. If the Python object is + ``Py_None`` then the string is ``NULL``. The integer uniquely + identifies the object in the context defined by the ``S`` format + character and allows an extra reference to the object to be kept to + ensure that the string remains valid. For Python v2 the object may be + either a string or a unicode object that can be encoded. For Python v3 + the object may either be a bytes object or a string object that can be + encoded. An object that supports the buffer protocol may also be used. + + ``B`` (string/bytes) [int, const char \*\*] + Convert a Python v2 string object or a Python v3 bytes object to a + C/C++ ``'\0'`` terminated string. If the Python object is ``Py_None`` + then the string is ``NULL``. The integer uniquely identifies the + object in the context defined by the ``S`` format character and allows + an extra reference to the object to be kept to ensure that the string + remains valid. + + ``Cf`` (wrapped class) [:ctype:`sipWrapperType` \*, int \*, void \*\*] + Convert a Python object to a C structure or a C++ class instance and + return its state as described in :cfunc:`sipConvertToInstance()`. + ``f`` is a combination of the following flags encoded as an ASCII + character by adding ``0`` to the combined value: + + 0x01 disallows the conversion of ``Py_None`` to ``NULL`` + + 0x02 implements the :fanno:`Factory` and :fanno:`TransferBack` + annotations + + 0x04 suppresses the return of the state of the returned C/C++ + instance. Note that the ``int *`` used to return the state is + not passed if this flag is specified. + + .. note:: + This is deprecated from SIP v4.8. Instead you should use ``Hf``. + + ``Df`` (wrapped instance) [const :ctype:`sipTypeDef` \*, int \*, void \*\*] + Convert a Python object to a C structure, C++ class or mapped type + instance and return its state as described in + :cfunc:`sipConvertToType()`. ``f`` is a combination of the following + flags encoded as an ASCII character by adding ``0`` to the combined + value: + + 0x01 disallows the conversion of ``Py_None`` to ``NULL`` + + 0x02 implements the :fanno:`Factory` and :fanno:`TransferBack` + annotations + + 0x04 suppresses the return of the state of the returned C/C++ + instance. Note that the ``int *`` used to return the state is + not passed if this flag is specified. + + .. note:: + This is deprecated from SIP v4.10.1. Instead you should use + ``Hf``. + + ``E`` (wrapped enum) [PyTypeObject \*, enum \*] + Convert a Python named enum type to the corresponding C/C++ ``enum``. + + .. note:: + This is deprecated from SIP v4.8. Instead you should use ``F``. + + ``F`` (wrapped enum) [:ctype:`sipTypeDef` \*, enum \*] + Convert a Python named enum type to the corresponding C/C++ ``enum``. + + ``G`` (unicode/string) [wchar_t \*\*, :cmacro:`SIP_SSIZE_T` \*] + Convert a Python v2 string or unicode object or a Python v3 string + object to a C/C++ wide character array and its length. If the Python + object is ``Py_None`` then the array and length are ``NULL`` and zero + respectively. + + ``Hf`` (wrapped instance) [const :ctype:`sipTypeDef` \*, int \*, void \*\*] + Convert a Python object to a C structure, C++ class or mapped type + instance as described in :cfunc:`sipConvertToType()`. ``f`` is a + combination of the following flags encoded as an ASCII character by + adding ``0`` to the combined value: + + 0x01 disallows the conversion of ``Py_None`` to ``NULL`` + + 0x02 implements the :fanno:`Factory` and :fanno:`TransferBack` + annotations + + 0x04 returns a copy of the C/C++ instance. + + ``N`` (object) [PyTypeObject \*, :PyObject \*\*] + A Python object is checked to see if it is a certain type and then + returned without any conversions. The reference count is incremented. + The Python object may be ``Py_None``. + + ``O`` (object) [PyObject \*\*] + A Python object is returned without any conversions. The reference + count is incremented. + + ``S`` [:ctype:`sipSimpleWrapper` \*] + This format character, if used, must be the first. It is used with + other format characters to define a context and doesn't itself convert + an argument. + + ``T`` (object) [PyTypeObject \*, PyObject \*\*] + A Python object is checked to see if it is a certain type and then + returned without any conversions. The reference count is incremented. + The Python object may not be ``Py_None``. + + ``V`` (:class:`sip.voidptr`) [void \*] + Convert a Python :class:`sip.voidptr` object to a C/C++ ``void *``. + + ``Z`` (object) [] + Check that a Python object is ``Py_None``. No value is returned. + + +.. cfunction:: int sipRegisterAttributeGetter(const sipTypeDef *td, sipAttrGetterFunc getter) + + This registers a handler that will called just before SIP needs to get an + attribute from a wrapped type's dictionary for the first time. The handler + must then populate the type's dictionary with any lazy attributes. + + :param td: + the optional :ref:`generated type structure <ref-type-structures>` that + determines which types the handler will be called for. + :param getter: + the handler function. + :return: + 0 if there was no error, otherwise -1 is returned. + + If *td* is not ``NULL`` then the handler will only be called for types with + that type or that are sub-classed from it. Otherwise the handler will be + called for all types. + + A handler has the following signature. + + int handler(const :ctype:`sipTypeDef` \*td, PyObject \*dict) + + *td* is the generated type definition of the type whose dictionary is + to be populated. + + *dict* is the dictionary to be populated. + + 0 if there was no error, otherwise -1 is returned. + + See the section :ref:`ref-lazy-type-attributes` for more details. + + +.. cfunction:: int sipRegisterPyType(PyTypeObject *type) + + This registers a Python type object that can be used as the meta-type or + super-type of a wrapped C++ type. + + :param type: + the type object. + :return: + 0 if there was no error, otherwise -1 is returned. + + See the section :ref:`ref-types-metatypes` for more details. + + +.. cfunction:: void sipReleaseInstance(void *cpp, sipWrapperType *type, int state) + + This destroys a wrapped C/C++ instance if it was a temporary instance. It + is called after a call to either :cfunc:`sipConvertToInstance()` or + :cfunc:`sipForceConvertToInstance()`. + + :param cpp: + the C/C++ instance. + :param type: + the type's :ref:`generated type object <ref-type-objects>`. + :param state: + describes the state of the C/C++ instance. + + .. note:: + This is deprecated from SIP v4.8. Instead you should use + :cfunc:`sipReleaseType()`. + + +.. cfunction:: void sipReleaseMappedType(void *cpp, const sipMappedType *mt, int state) + + This destroys a wrapped C/C++ mapped type if it was a temporary instance. + It is called after a call to either :cfunc:`sipConvertToMappedType()` or + :cfunc:`sipForceConvertToMappedType()`. + + :param cpp: + the C/C++ instance. + :param mt: + the opaque structure returned by :cfunc:`sipFindMappedType()`. + :param state: + describes the state of the C/C++ instance. + + .. note:: + This is deprecated from SIP v4.8. Instead you should use + :cfunc:`sipReleaseType()`. + + +.. cfunction:: void sipReleaseType(void *cpp, const sipTypeDef *td, int state) + + This destroys a wrapped C/C++ or mapped type instance if it was a temporary + instance. It is called after a call to either :cfunc:`sipConvertToType()` + or :cfunc:`sipForceConvertToType()`. + + :param cpp: + the C/C++ instance. + :param td: + the type's :ref:`generated type structure <ref-type-structures>`. + :param state: + describes the state of the C/C++ instance. + + +.. cfunction:: const char *sipResolveTypedef(const char *name) + + This returns the value of a C/C++ typedef. + + :param name: + the name of the typedef. + :return: + the value of the typedef or ``NULL`` if there was no such typedef. + + +.. ctype:: sipSimpleWrapper + + This is a C structure that represents a Python wrapped instance whose type + is :class:`sip.simplewrapper`. It is an extension of the ``PyObject`` + structure and so may be safely cast to it. + + .. cmember:: PyObject *user + + This can be used for any purpose by handwritten code and will + automatically be garbage collected at the appropriate time. + + +.. cvar:: PyTypeObject *sipSimpleWrapper_Type + + This is the type of a :ctype:`sipSimpleWrapper` structure and is the C + implementation of :class:`sip.simplewrapper`. It may be safely cast to + :ctype:`sipWrapperType`. + + +.. ctype:: sipStringTypeClassMap + + This C structure is used with :cfunc:`sipMapStringToClass()` to define a + mapping between ``'\0'`` terminated string based RTTI and + :ref:`ref-type-objects`. The structure elements are as follows. + + .. cmember:: char *typeString + + The ``'\0'`` terminated string RTTI. + + .. cmember:: sipWrapperType **pyType. + + A pointer to the corresponding generated type object. + + .. note:: + This is deprecated from SIP v4.8. + + +.. cfunction:: void sipTransferBack(PyObject *obj) + + This transfers ownership of a Python wrapped instance to Python (see + :ref:`ref-object-ownership`). + + :param obj: + the wrapped instance. + + In addition, any association of the instance with regard to the cyclic + garbage collector with another instance is removed. + + +.. cfunction:: void sipTransferBreak(PyObject *obj) + + Any association of a Python wrapped instance with regard to the cyclic + garbage collector with another instance is removed. Ownership of the + instance should be with C++. + + :param obj: + the wrapped instance. + + +.. cfunction:: void sipTransferTo(PyObject *obj, PyObject *owner) + + This transfers ownership of a Python wrapped instance to C++ (see + :ref:`ref-object-ownership`). + + :param obj: + the wrapped instance. + :param owner: + an optional wrapped instance that *obj* becomes associated with with + regard to the cyclic garbage collector. If *owner* is ``NULL`` then no + such association is made. If *owner* is the same value as *obj* then + any reference cycles involving *obj* can never be detected or broken by + the cyclic garbage collector. Responsibility for calling the C++ + instance's destructor is always transfered to C++. + + +.. cfunction:: PyTypeObject *sipTypeAsPyTypeObject(sipTypeDef *td) + + This returns a pointer to the Python type object that SIP creates for a + :ref:`generated type structure <ref-type-structures>`. + + :param td: + the type structure. + :return: + the Python type object. If the type structure refers to a mapped type + then ``NULL`` will be returned. + + If the type structure refers to a C structure or C++ class then the + Python type object may be safely cast to a :ctype:`sipWrapperType`. + + +.. cfunction:: const sipTypeDef *sipTypeFromPyTypeObject(PyTypeObject *py_type) + + This returns the :ref:`generated type structure <ref-type-structures>` for + a Python type object. + + :param py_type: + the Python type object. + :return: + the type structure or ``NULL`` if the Python type object doesn't + correspond to a type structure. + + +.. cfunction:: int sipTypeIsClass(sipTypeDef *td) + + This checks if a :ref:`generated type structure <ref-type-structures>` + refers to a C structure or C++ class. + + :param td: + the type structure. + :return: + a non-zero value if the type structure refers to a structure or class. + + +.. cfunction:: int sipTypeIsEnum(sipTypeDef *td) + + This checks if a :ref:`generated type structure <ref-type-structures>` + refers to a named enum. + + :param td: + the type structure. + :return: + a non-zero value if the type structure refers to an enum. + + +.. cfunction:: int sipTypeIsMapped(sipTypeDef *td) + + This checks if a :ref:`generated type structure <ref-type-structures>` + refers to a mapped type. + + :param td: + the type structure. + :return: + a non-zero value if the type structure refers to a mapped type. + + +.. cfunction:: int sipTypeIsNamespace(sipTypeDef *td) + + This checks if a :ref:`generated type structure <ref-type-structures>` + refers to a C++ namespace. + + :param td: + the type structure. + :return: + a non-zero value if the type structure refers to a namespace. + + +.. cfunction:: const char *sipTypeName(const sipTypeDef *td) + + This returns the C/C++ name of a wrapped type. + + :param td: + the type's :ref:`generated type structure <ref-type-structures>`. + :return: + the name of the C/C++ type. + + +.. cfunction:: const sipTypeDef *sipTypeScope(const sipTypeDef *td) + + This returns the :ref:`generated type structure <ref-type-structures>` of + the enclosing scope of another generated type structure. + + :param td: + the type structure. + :return: + the type structure of the scope or ``NULL`` if the type has no scope. + + +.. cvar:: PyTypeObject *sipVoidPtr_Type + + This is the type of a ``PyObject`` structure that is used to wrap a + ``void *``. + + +.. ctype:: sipWrapper + + This is a C structure that represents a Python wrapped instance whose type + is :class:`sip.wrapper`. It is an extension of the + :ctype:`sipSimpleWrapper` and ``PyObject`` structures and so may be safely + cast to both. + + +.. cfunction:: int sipWrapper_Check(PyObject *obj) + + This checks if a Python object is a wrapped instance. + + :param obj: + the Python object. + :return: + a non-zero value if the Python object is a wrapped instance. + + .. note:: + This is deprecated from SIP v4.8. Instead you should use the + following:: + + PyObject_TypeCheck(obj, sipWrapper_Type) + + +.. cvar:: PyTypeObject *sipWrapper_Type + + This is the type of a :ctype:`sipWrapper` structure and is the C + implementation of :class:`sip.wrapper`. It may be safely cast to + :ctype:`sipWrapperType`. + + +.. ctype:: sipWrapperType + + This is a C structure that represents a SIP generated type object. It is + an extension of the ``PyTypeObject`` structure (which is itself an + extension of the ``PyObject`` structure) and so may be safely cast to + ``PyTypeObject`` (and ``PyObject``). + + +.. cvar:: PyTypeObject *sipWrapperType_Type + + This is the type of a :ctype:`sipWrapperType` structure and is the C + implementation of :class:`sip.wrappertype`. + + +.. _ref-type-structures: + +Generated Type Structures +------------------------- + +SIP generates an opaque type structure for each C structure, C++ class, C++ +namespace, named enum or mapped type being wrapped. These are +:ctype:`sipTypeDef` structures and are used extensively by the SIP API. + +The names of these structure are prefixed by ``sipType_``. + +For those structures 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 name. Any ``::`` +scope separators are replaced by an underscore. For example, the type object +for class ``Klass`` is ``sipType_Klass``. + +For those structure 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 structure for a mapped type is to use :cfunc:`sipFindType()`. + +The type structures of all imported types are available to handwritten code. + + +.. _ref-type-objects: + +Generated Type Objects +---------------------- + +SIP generates a :ctype:`sipWrapperType` type object for each C structure or +C++ class being wrapped. + +These objects are named with the structure or class name prefixed by +``sipClass_``. For example, the type object for class ``Klass`` is +``sipClass_Klass``. + +.. note:: + Using these names is deprecated from SIP v4.8. Instead use the + corresponding generated type structure (see :ref:`ref-type-structures`) and + :cfunc:`sipTypeAsPyTypeObject()`. + + +.. _ref-enum-type-objects: + +Generated Named Enum Type Objects +--------------------------------- + +SIP generates a type object for each named enum being wrapped. These are +PyTypeObject structures. (Anonymous enums are wrapped as Python integers.) + +These objects are named with the fully qualified enum name (i.e. including any +enclosing scope) prefixed by ``sipEnum_``. For example, the type object for +enum ``Enum`` defined in class ``Klass`` is ``sipEnum_Klass_Enum``. + +.. note:: + Using these names is deprecated from SIP v4.8. Instead use the + corresponding generated type structure (see :ref:`ref-type-structures`) and + :cfunc:`sipTypeAsPyTypeObject()`. + + +.. _ref-derived-classes: + +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, or does not emit any Qt signals, 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 +:directive:`%MethodCode` directive should call the derived class's constructor +(which has the same C++ signature) rather then the wrapped class's constructor. + + +.. _ref-exception-objects: + +Generated Exception Objects +--------------------------- + +SIP generates a Python object for each exception defined with the +:directive:`%Exception` directive. + +These objects are named with the fully qualified exception name (i.e. including +any enclosing scope) prefixed by ``sipException_``. For example, the type +object for enum ``Except`` defined in class ``Klass`` is +``sipException_Klass_Except``. + +The objects of all imported exceptions are available to handwritten code. diff --git a/sphinx/command_line.rst b/sphinx/command_line.rst new file mode 100644 index 0000000..9c50cf4 --- /dev/null +++ b/sphinx/command_line.rst @@ -0,0 +1,137 @@ +.. _ref-command-line: + +The SIP Command Line +==================== + +The syntax of the SIP command line is:: + + sip [options] [specification] + +``specification`` is the name of the specification file for the module. If it +is omitted then ``stdin`` is used. + +The full set of command line options is: + +.. program:: sip + +.. cmdoption:: -h + + Display a help message. + +.. cmdoption:: -V + + Display the SIP version number. + +.. cmdoption:: -a <FILE> + + The name of the QScintilla API file to generate. This file contains a + description of the module API in a form that the QScintilla editor + component can use for auto-completion and call tips. (The file may also be + used by the SciTE editor but must be sorted first.) By default the file is + not generated. + +.. cmdoption:: -b <FILE> + + The name of the build file to generate. This file contains the information + about the module needed by the :ref:`SIP build system <ref-build-system>` + to generate a platform and compiler specific Makefile for the module. By + default the file is not generated. + +.. cmdoption:: -c <DIR> + + The name of the directory (which must exist) into which all of the + generated C or C++ code is placed. By default no code is generated. + +.. cmdoption:: -d <FILE> + + The name of the documentation file to generate. Documentation is included + in specification files using the :directive:`%Doc` and + :directive:`%ExportedDoc` directives. By default the file is not + generated. + +.. cmdoption:: -e + + Support for C++ exceptions is enabled. This causes all calls to C++ code + to be enclosed in ``try``/``catch`` blocks and C++ exceptions to be + converted to Python exceptions. By default exception support is disabled. + +.. cmdoption:: -g + + The Python GIL is released before making any calls to the C/C++ library + being wrapped and reacquired afterwards. See :ref:`ref-gil` and the + :fanno:`ReleaseGIL` and :fanno:`HoldGIL` annotations. + +.. cmdoption:: -I <DIR> + + The directory is added to the list of directories searched when looking for + a specification file given in an :directive:`%Include` or + :directive:`%Import` directive. This option may be given any number of + times. + +.. cmdoption:: -j <NUMBER> + + The generated code is split into the given number of files. This makes it + easier to use the parallel build facility of most modern implementations of + ``make``. By default 1 file is generated for each C structure or C++ + class. + +.. cmdoption:: -k + + .. versionadded:: 4.10 + + All functions and methods will, by default, support passing parameters + using the Python keyword argument syntax. + +.. cmdoption:: -o + + .. versionadded:: 4.10 + + Docstrings will be automatically generated that describe the signature of + all functions, methods and constructors. + +.. cmdoption:: -p <MODULE> + + The name of the :directive:`%ConsolidatedModule` which will contain the + wrapper code for this component module. + +.. cmdoption:: -P + + .. versionadded:: 4.10 + + By default SIP generates code to provide access to protected C++ functions + from Python. On some platforms (notably Linux, but not Windows) this code + can be avoided if the ``protected`` keyword is redefined as ``public`` + during compilation. This can result in a significant reduction in the size + of a generated Python module. This option disables the generation of the + extra code. + +.. cmdoption:: -r + + Debugging statements that trace the execution of the bindings are + automatically generated. By default the statements are not generated. + +.. cmdoption:: -s <SUFFIX> + + The suffix to use for generated C or C++ source files. By default ``.c`` + is used for C and ``.cpp`` for C++. + +.. cmdoption:: -t <TAG> + + The SIP version tag (declared using a :directive:`%Timeline` directive) or + the SIP platform tag (declared using the :directive:`%Platforms` directive) + to generate code for. This option may be given any number of times so long + as the tags do not conflict. + +.. cmdoption:: -w + + The display of warning messages is enabled. By default warning messages + are disabled. + +.. cmdoption:: -x <FEATURE> + + The feature (declared using the :directive:`%Feature` directive) is + disabled. + +.. cmdoption:: -z <FILE> + + The name of a file containing more command line options. diff --git a/sphinx/conf.py b/sphinx/conf.py new file mode 100644 index 0000000..43a3a1e --- /dev/null +++ b/sphinx/conf.py @@ -0,0 +1,231 @@ +# -*- coding: utf-8 -*- +# +# SIP documentation build configuration file, created by +# sphinx-quickstart on Sat May 30 14:28:55 2009. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.append(os.path.abspath('.')) + +# -- General configuration ----------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +#extensions = [] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'SIP' +copyright = u'2010 Riverbank Computing Limited' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '4.10.5' +# The full version, including alpha/beta/rc tags. +release = '4.10.5' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of documents that shouldn't be included in the build. +#unused_docs = [] + +# List of directories, relative to source directory, that shouldn't be searched +# for source files. +#exclude_trees = [] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. Major themes that come with +# Sphinx are currently 'default' and 'sphinxdoc'. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# "<project> v<release> documentation". +html_title = "SIP 4.10.5 Reference Guide" + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_use_modindex = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +html_show_sourcelink = False + +# If true, an OpenSearch description file will be output, and all pages will +# contain a <link> tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = '' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'SIPdoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +# The paper size ('letter' or 'a4'). +#latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +#latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'SIP.tex', u'SIP Documentation', + u'Riverbank Computing Limited', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# Additional stuff for the LaTeX preamble. +#latex_preamble = '' + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_use_modindex = True + + +def setup(app): + """ Define roles specific to SIP. """ + + app.add_description_unit('argument-annotation', 'aanno', + indextemplate='single: %s (argument annotation)') + + app.add_description_unit('class-annotation', 'canno', + indextemplate='single: %s (class annotation)') + + app.add_description_unit('enum-annotation', 'eanno', + indextemplate='single: %s (enum annotation)') + + app.add_description_unit('exception-annotation', 'xanno', + indextemplate='single: %s (exception annotation)') + + app.add_description_unit('function-annotation', 'fanno', + indextemplate='single: %s (function annotation)') + + app.add_description_unit('license-annotation', 'lanno', + indextemplate='single: %s (license annotation)') + + app.add_description_unit('mapped-type-annotation', 'manno', + indextemplate='single: %s (mapped type annotation)') + + app.add_description_unit('typedef-annotation', 'tanno', + indextemplate='single: %s (typedef annotation)') + + app.add_description_unit('variable-annotation', 'vanno', + indextemplate='single: %s (variable annotation)') + + app.add_description_unit('directive', 'directive', + indextemplate='single: %s (directive)') + + app.add_description_unit('sip-type', 'stype', + indextemplate='single: %s (SIP type)') diff --git a/sphinx/directives.rst b/sphinx/directives.rst new file mode 100644 index 0000000..7e3a2e0 --- /dev/null +++ b/sphinx/directives.rst @@ -0,0 +1,2109 @@ +Directives +========== + +In this section we describe each of the directives that can be used in +specification files. All directives begin with ``%`` as the first +non-whitespace character in a line. + +Some directives have arguments or contain blocks of code or documentation. In +the following descriptions these are shown in *italics*. Optional arguments +are enclosed in [*brackets*]. + +Some directives are used to specify handwritten code. Handwritten code must +not define names that start with the prefix ``sip``. + + +.. directive:: %AccessCode + +.. parsed-literal:: + + %AccessCode + *code* + %End + +This directive is used immediately after the declaration of an instance of a +wrapped class or structure, or a pointer to such an instance. You use it to +provide handwritten code that overrides the default behaviour. + +For example:: + + class Klass; + + Klass *klassInstance; + %AccessCode + // In this contrived example the C++ library we are wrapping defines + // klassInstance as Klass ** (which SIP doesn't support) so we + // explicitly dereference it. + if (klassInstance && *klassInstance) + return *klassInstance; + + // This will get converted to None. + return 0; + %End + + +.. directive:: %API + +.. versionadded:: 4.9 + +.. parsed-literal:: + + %API *name* *version* + +This directive is used to define an API and set its default version number. A +version number must be greater than or equal to 1. + +See :ref:`ref-incompat-apis` for more detail. + +For example:: + + %API PyQt4 1 + + +.. directive:: %BIGetBufferCode + +.. parsed-literal:: + + %BIGetBufferCode + *code* + %End + +This directive (along with :directive:`%BIReleaseBufferCode`) is used to +specify code that implements the buffer interface of Python v3. If Python v2 +is being used then this is ignored. + +The following variables are made available to the handwritten code: + +Py_buffer \*sipBuffer + This is a pointer to the Python buffer structure that the handwritten code + must populate. + +*type* \*sipCpp + This is a pointer to the structure or class instance. Its *type* is a + pointer to the structure or class. + +int sipFlags + These are the flags that specify what elements of the ``sipBuffer`` + structure must be populated. + +int sipRes + The handwritten code should set this to 0 if there was no error or -1 if + there was an error. + +PyObject \*sipSelf + This is the Python object that wraps the structure or class instance, i.e. + ``self``. + + +.. directive:: %BIGetCharBufferCode + +.. parsed-literal:: + + %BIGetCharBufferCode + *code* + %End + +This directive (along with :directive:`%BIGetReadBufferCode`, +:directive:`%BIGetSegCountCode` and :directive:`%BIGetWriteBufferCode`) is used +to specify code that implements the buffer interface of Python v2. If Python +v3 is being used then this is ignored. + +The following variables are made available to the handwritten code: + +*type* \*sipCpp + This is a pointer to the structure or class instance. Its *type* is a + pointer to the structure or class. + +void \*\*sipPtrPtr + This is the pointer used to return the address of the character buffer. + +:cmacro:`SIP_SSIZE_T` sipRes + The handwritten code should set this to the length of the character buffer + or -1 if there was an error. + +:cmacro:`SIP_SSIZE_T` sipSegment + This is the number of the segment of the character buffer. + +PyObject \*sipSelf + This is the Python object that wraps the structure or class instance, i.e. + ``self``. + + +.. directive:: %BIGetReadBufferCode + +.. parsed-literal:: + + %BIGetReadBufferCode + *code* + %End + +This directive (along with :directive:`%BIGetCharBufferCode`, +:directive:`%BIGetSegCountCode` and :directive:`%BIGetWriteBufferCode`) is used +to specify code that implements the buffer interface of Python v2. If +Python v3 is being used then this is ignored. + +The following variables are made available to the handwritten code: + +*type* \*sipCpp + This is a pointer to the structure or class instance. Its *type* is a + pointer to the structure or class. + +void \*\*sipPtrPtr + This is the pointer used to return the address of the read buffer. + +:cmacro:`SIP_SSIZE_T` sipRes + The handwritten code should set this to the length of the read buffer or + -1 if there was an error. + +:cmacro:`SIP_SSIZE_T` sipSegment + This is the number of the segment of the read buffer. + +PyObject \*sipSelf + This is the Python object that wraps the structure or class instance, i.e. + ``self``. + + +.. directive:: %BIGetSegCountCode + +.. parsed-literal:: + + %BIGetSegCountCode + *code* + %End + +This directive (along with :directive:`%BIGetCharBufferCode`, +:directive:`%BIGetReadBufferCode` and :directive:`%BIGetWriteBufferCode`) is +used to specify code that implements the buffer interface of Python v2. If +Python v3 is being used then this is ignored. + +The following variables are made available to the handwritten code: + +*type* \*sipCpp + This is a pointer to the structure or class instance. Its *type* is a + pointer to the structure or class. + +:cmacro:`SIP_SSIZE_T` \*sipLenPtr + This is the pointer used to return the total length in bytes of all + segments of the buffer. + +:cmacro:`SIP_SSIZE_T` sipRes + The handwritten code should set this to the number of segments that make + up the buffer. + +PyObject \*sipSelf + This is the Python object that wraps the structure or class instance, i.e. + ``self``. + + +.. directive:: %BIGetWriteBufferCode + +.. parsed-literal:: + + %BIGetWriteBufferCode + *code* + %End + +This directive (along with :directive:`%BIGetCharBufferCode`, +:directive:`%BIGetReadBufferCode` and :directive:`%BIGetSegCountCode` is used +to specify code that implements the buffer interface of Python v2. If Python +v3 is being used then this is ignored. + +The following variables are made available to the handwritten code: + +*type* \*sipCpp + This is a pointer to the structure or class instance. Its *type* is a + pointer to the structure or class. + +void \*\*sipPtrPtr + This is the pointer used to return the address of the write buffer. + +:cmacro:`SIP_SSIZE_T` sipRes + The handwritten code should set this to the length of the write buffer or + -1 if there was an error. + +:cmacro:`SIP_SSIZE_T` sipSegment + This is the number of the segment of the write buffer. + +PyObject \*sipSelf + This is the Python object that wraps the structure or class instance, i.e. + ``self``. + + +.. directive:: %BIReleaseBufferCode + +.. parsed-literal:: + + %BIReleaseBufferCode + *code* + %End + +This directive (along with :directive:`%BIGetBufferCode`) is used to specify +code that implements the buffer interface of Python v3. If Python v2 is being +used then this is ignored. + +The following variables are made available to the handwritten code: + +Py_buffer \*sipBuffer + This is a pointer to the Python buffer structure. + +*type* \*sipCpp + This is a pointer to the structure or class instance. Its *type* is a + pointer to the structure or class. + +PyObject \*sipSelf + This is the Python object that wraps the structure or class instance, i.e. + ``self``. + + +.. directive:: %CModule + +.. parsed-literal:: + + %CModule *name* [*version*] + +This directive is used to identify that the library being wrapped is a C +library and to define the name of the module and it's optional version number. + +See the :directive:`%Module` directive for an explanation of the version +number. + +For example:: + + %CModule dbus 1 + + +.. directive:: %CompositeModule + +.. parsed-literal:: + + %CompositeModule *name* + +A composite module is one that merges a number of related SIP generated +modules. For example, a module that merges the modules ``a_mod``, ``b_mod`` +and ``c_mod`` is equivalent to the following pure Python module:: + + from a_mod import * + from b_mod import * + from c_mod import * + +Clearly the individual modules should not define module-level objects with the +same name. + +This directive is used to specify the name of a composite module. Any +subsequent :directive:`%CModule` or :directive:`%Module` directive is +interpreted as defining a component module. + +For example:: + + %CompositeModule PyQt4.Qt + %Include QtCore/QtCoremod.sip + %Include QtGui/QtGuimod.sip + +The main purpose of a composite module is as a programmer convenience as they +don't have to remember which which individual module an object is defined in. + + +.. directive:: %ConsolidatedModule + +.. parsed-literal:: + + %ConsolidatedModule *name* + +A consolidated module is one that consolidates the wrapper code of a number of +SIP generated modules (refered to as component modules in this context). + +This directive is used to specify the name of a consolidated module. Any +subsequent :directive:`%CModule` or :directive:`%Module` directive is +interpreted as defining a component module. + +For example:: + + %ConsolidatedModule PyQt4._qt + %Include QtCore/QtCoremod.sip + %Include QtGui/QtGuimod.sip + +A consolidated module is not intended to be explicitly imported by an +application. Instead it is imported by its component modules when they +themselves are imported. + +Normally the wrapper code is contained in the component module and is linked +against the corresponding C or C++ library. The advantage of a consolidated +module is that it allows all of the wrapped C or C++ libraries to be linked +against a single module. If the linking is done statically then deployment of +generated modules can be greatly simplified. + +It follows that a component module can be built in one of two ways, as a +normal standalone module, or as a component of a consolidated module. When +building as a component the ``-p`` command line option should be used to +specify the name of the consolidated module. + + +.. directive:: %ConvertFromTypeCode + +.. parsed-literal:: + + %ConvertFromTypeCode + *code* + %End + +This directive is used as part of the :directive:`%MappedType` directive to +specify the handwritten code that converts an instance of a mapped type to a +Python object. + +The following variables are made available to the handwritten code: + +*type* \*sipCpp + This is a pointer to the instance of the mapped type to be converted. It + will never be zero as the conversion from zero to ``Py_None`` is handled + before the handwritten code is called. + +PyObject \*sipTransferObj + This specifies any desired ownership changes to the returned object. If it + is ``NULL`` then the ownership should be left unchanged. If it is + ``Py_None`` then ownership should be transferred to Python. Otherwise + ownership should be transferred to C/C++ and the returned object associated + with *sipTransferObj*. The code can choose to interpret these changes in + any way. For example, if the code is converting a C++ container of wrapped + classes to a Python list it is likely that the ownership changes should be + made to each element of the list. + +The handwritten code must explicitly return a ``PyObject *``. If there was an +error then a Python exception must be raised and ``NULL`` returned. + +The following example converts a ``QList<QWidget *>`` instance to a Python +list of ``QWidget`` instances:: + + %ConvertFromTypeCode + PyObject *l; + + // Create the Python list of the correct length. + if ((l = PyList_New(sipCpp->size())) == NULL) + return NULL; + + // Go through each element in the C++ instance and convert it to a + // wrapped QWidget. + for (int i = 0; i < sipCpp->size(); ++i) + { + QWidget *w = sipCpp->at(i); + PyObject *wobj; + + // Get the Python wrapper for the QWidget instance, creating a new + // one if necessary, and handle any ownership transfer. + if ((wobj = sipConvertFromType(w, sipType_QWidget, sipTransferObj)) == NULL) + { + // There was an error so garbage collect the Python list. + Py_DECREF(l); + return NULL; + } + + // Add the wrapper to the list. + PyList_SET_ITEM(l, i, wobj); + } + + // Return the Python list. + return l; + %End + + +.. directive:: %ConvertToSubClassCode + +.. parsed-literal:: + + %ConvertToSubClassCode + *code* + %End + +When SIP needs to wrap a C++ class instance it first checks to make sure it +hasn't already done so. If it has then it just returns a new reference to the +corresponding Python object. Otherwise it creates a new Python object of the +appropriate type. In C++ a function may be defined to return an instance of a +certain class, but can often return a sub-class instead. + +This directive is used to specify handwritten code that exploits any available +real-time type information (RTTI) to see if there is a more specific Python +type that can be used when wrapping the C++ instance. The RTTI may be +provided by the compiler or by the C++ instance itself. + +The directive is included in the specification of one of the classes that the +handwritten code handles the type conversion for. It doesn't matter which +one, but a sensible choice would be the one at the root of that class +hierarchy in the module. + +Note that if a class hierarchy extends over a number of modules then this +directive should be used in each of those modules to handle the part of the +hierarchy defined in that module. SIP will ensure that the different pieces +of code are called in the right order to determine the most specific Python +type to use. + +The following variables are made available to the handwritten code: + +*type* \*sipCpp + This is a pointer to the C++ class instance. + +void \*\*sipCppRet + When the sub-class is derived from more than one super-class then it is + possible that the C++ address of the instance as the sub-class is + different to that of the super-class. If so, then this must be set to the + C++ address of the instance when cast (usually using ``static_cast``) + from the super-class to the sub-class. + +const sipTypeDef \*sipType + The handwritten code must set this to the SIP generated type structure + that corresponds to the class instance. (The type structure for class + ``Klass`` is ``sipType_Klass``.) If the RTTI of the class instance isn't + recognised then ``sipType`` must be set to ``NULL``. The code doesn't + have to recognise the exact class, only the most specific sub-class that + it can. + +sipWrapperType \*sipClass + The handwritten code must set this to the SIP generated Python type object + that corresponds to the class instance. (The type object for class + ``Klass`` is ``sipClass_Klass``.) If the RTTI of the class instance isn't + recognised then ``sipClass`` must be set to ``NULL``. The code doesn't + have to recognise the exact class, only the most specific sub-class that + it can. + + This is deprecated from SIP v4.8. Instead you should use ``sipType``. + +The handwritten code must not explicitly return. + +The following example shows the sub-class conversion code for ``QEvent`` based +class hierarchy in PyQt:: + + class QEvent + { + %ConvertToSubClassCode + // QEvent sub-classes provide a unique type ID. + switch (sipCpp->type()) + { + case QEvent::Timer: + sipType = sipType_QTimerEvent; + break; + + case QEvent::KeyPress: + case QEvent::KeyRelease: + sipType = sipType_QKeyEvent; + break; + + // Skip the remaining event types to keep the example short. + + default: + // We don't recognise the type. + sipType = NULL; + } + %End + + // The rest of the class specification. + + }; + + +.. directive:: %ConvertToTypeCode + +.. parsed-literal:: + + %ConvertToTypeCode + *code* + %End + +This directive is used to specify the handwritten code that converts a Python +object to a mapped type instance and to handle any ownership transfers. It is +used as part of the :directive:`%MappedType` directive and as part of a class +specification. The code is also called to determine if the Python object is of +the correct type prior to conversion. + +When used as part of a class specification it can automatically convert +additional types of Python object. For example, PyQt uses it in the +specification of the ``QString`` class to allow Python string objects and +unicode objects to be used wherever ``QString`` instances are expected. + +The following variables are made available to the handwritten code: + +int \*sipIsErr + If this is ``NULL`` then the code is being asked to check the type of the + Python object. The check must not have any side effects. Otherwise the + code is being asked to convert the Python object and a non-zero value + should be returned through this pointer if an error occurred during the + conversion. + +PyObject \*sipPy + This is the Python object to be converted. + +*type* \*\*sipCppPtr + This is a pointer through which the address of the mapped type instance (or + zero if appropriate) is returned. Its value is undefined if ``sipIsErr`` + is ``NULL``. + +PyObject \*sipTransferObj + This specifies any desired ownership changes to *sipPy*. If it is ``NULL`` + then the ownership should be left unchanged. If it is ``Py_None`` then + ownership should be transferred to Python. Otherwise ownership should be + transferred to C/C++ and *sipPy* associated with *sipTransferObj*. The + code can choose to interpret these changes in any way. + +The handwritten code must explicitly return an ``int`` the meaning of which +depends on the value of ``sipIsErr``. + +If ``sipIsErr`` is ``NULL`` then a non-zero value is returned if the Python +object has a type that can be converted to the mapped type. Otherwise zero is +returned. + +If ``sipIsErr`` is not ``NULL`` then a combination of the following flags is +returned. + + - :cmacro:`SIP_TEMPORARY` is set to indicate that the returned instance + is a temporary and should be released to avoid a memory leak. + + - :cmacro:`SIP_DERIVED_CLASS` is set to indicate that the type of the + returned instance is a derived class. See + :ref:`ref-derived-classes`. + +The following example converts a Python list of ``QPoint`` instances to a +``QList<QPoint>`` instance:: + + %ConvertToTypeCode + // See if we are just being asked to check the type of the Python + // object. + if (!sipIsErr) + { + // Checking whether or not None has been passed instead of a list + // has already been done. + if (!PyList_Check(sipPy)) + return 0; + + // Check the type of each element. We specify SIP_NOT_NONE to + // disallow None because it is a list of QPoint, not of a pointer + // to a QPoint, so None isn't appropriate. + for (int i = 0; i < PyList_GET_SIZE(sipPy); ++i) + if (!sipCanConvertToType(PyList_GET_ITEM(sipPy, i), + sipType_QPoint, SIP_NOT_NONE)) + return 0; + + // The type is valid. + return 1; + } + + // Create the instance on the heap. + QList<QPoint> *ql = new QList<QPoint>; + + for (int i = 0; i < PyList_GET_SIZE(sipPy); ++i) + { + QPoint *qp; + int state; + + // Get the address of the element's C++ instance. Note that, in + // this case, we don't apply any ownership changes to the list + // elements, only to the list itself. + qp = reinterpret_cast<QPoint *>(sipConvertToType( + PyList_GET_ITEM(sipPy, i), + sipType_QPoint, 0, + SIP_NOT_NONE, + &state, sipIsErr)); + + // Deal with any errors. + if (*sipIsErr) + { + sipReleaseType(qp, sipType_QPoint, state); + + // Tidy up. + delete ql; + + // There is no temporary instance. + return 0; + } + + ql->append(*qp); + + // A copy of the QPoint was appended to the list so we no longer + // need it. It may be a temporary instance that should be + // destroyed, or a wrapped instance that should not be destroyed. + // sipReleaseType() will do the right thing. + sipReleaseType(qp, sipType_QPoint, state); + } + + // Return the instance. + *sipCppPtr = ql; + + // The instance should be regarded as temporary (and be destroyed as + // soon as it has been used) unless it has been transferred from + // Python. sipGetState() is a convenience function that implements + // this common transfer behaviour. + return sipGetState(sipTransferObj); + %End + +When used in a class specification the handwritten code replaces the code that +would normally be automatically generated. This means that the handwritten +code must also handle instances of the class itself and not just the additional +types that are being supported. This should be done by making calls to +:cfunc:`sipCanConvertToType()` to check the object type and +:cfunc:`sipConvertToType()` to convert the object. The +:cmacro:`SIP_NO_CONVERTORS` flag *must* be passed to both these functions to +prevent recursive calls to the handwritten code. + + +.. directive:: %Copying + +.. parsed-literal:: + + %Copying + *text* + %End + +This directive is used to specify some arbitrary text that will be included at +the start of all source files generated by SIP. It is normally used to +include copyright and licensing terms. + +For example:: + + %Copying + Copyright (c) 2009 Riverbank Computing Limited + %End + + +.. directive:: %DefaultEncoding + +.. parsed-literal:: + + %DefaultEncoding *string* + +This directive is used to specify the default encoding used for ``char``, +``const char``, ``char *`` or ``const char *`` values. The encoding can be +either ``"ASCII"``, ``"Latin-1"``, ``"UTF-8"`` or ``"None"``. An encoding of +``"None"`` means that the value is unencoded. The default can be overridden +for a particular value using the :aanno:`Encoding` annotation. If the +directive is not specified then ``"None"`` is used. + +For example:: + + %DefaultEncoding "Latin-1" + + +.. directive:: %DefaultMetatype + +.. parsed-literal:: + + %DefaultMetatype *dotted-name* + +This directive is used to specify the Python type that should be used as the +meta-type for any C/C++ data type defined in the same module, and by importing +modules, that doesn't have an explicit meta-type. + +If this is not specified then ``sip.wrappertype`` is used. + +You can also use the :canno:`Metatype` class annotation to specify the +meta-type used by a particular C/C++ type. + +See the section :ref:`ref-types-metatypes` for more details. + +For example:: + + %DefaultMetatype PyQt4.QtCore.pyqtWrapperType + + +.. directive:: %DefaultSupertype + +.. parsed-literal:: + + %DefaultSupertype *dotted-name* + +This directive is used to specify the Python type that should be used as the +super-type for any C/C++ data type defined in the same module that doesn't have +an explicit super-type. + +If this is not specified then ``sip.wrapper`` is used. + +You can also use the :canno:`Supertype` class annotation to specify the +super-type used by a particular C/C++ type. + +See the section :ref:`ref-types-metatypes` for more details. + +For example:: + + %DefaultSupertype sip.simplewrapper + + +.. directive:: %Doc + +.. parsed-literal:: + + %Doc + *text* + %End + +This directive is used to specify some arbitrary text that will be extracted +by SIP when the ``-d`` command line option is used. The directive can be +specified any number of times and SIP will concatenate all the separate pieces +of text in the order that it sees them. + +Documentation that is specified using this directive is local to the module in +which it appears. It is ignored by modules that :directive:`%Import` it. Use +the :directive:`%ExportedDoc` directive for documentation that should be +included by all modules that :directive:`%Import` this one. + +For example:: + + %Doc + <h1>An Example</h1> + <p> + This fragment of documentation is HTML and is local to the module in + which it is defined. + </p> + %End + + +.. directive:: %Docstring + +.. parsed-literal:: + + %Docstring + *text* + %End + +.. versionadded:: 4.10 + +This directive is used to specify explicit docstrings for classes, functions +and methods. + +The docstring of a class is made up of the docstring specified for the class +itself, with the docstrings specified for each contructor appended. + +The docstring of a function or method is made up of the concatenated docstrings +specified for each of the overloads. + +Specifying an explicit docstring will prevent SIP from generating an automatic +docstring that describes the Python signature of a function or method overload. +This means that SIP will generate less informative exceptions (i.e. without a +full signature) when it fails to match a set of arguments to any function or +method overload. + +For example:: + + class Klass + { + %Docstring + This will be at the start of the class's docstring. + %End + + public: + Klass(); + %Docstring + This will be appended to the class's docstring. + %End + }; + + +.. directive:: %End + +This isn't a directive in itself, but is used to terminate a number of +directives that allow a block of handwritten code or text to be specified. + + +.. directive:: %Exception + +.. parsed-literal:: + + %Exception *name* [(*base-exception)] + { + [*header-code*] + *raise-code* + }; + +This directive is used to define new Python exceptions, or to provide a stub +for existing Python exceptions. It allows handwritten code to be provided +that implements the translation between C++ exceptions and Python exceptions. +The arguments to ``throw ()`` specifiers must either be names of classes or the +names of Python exceptions defined by this directive. + +*name* is the name of the exception. + +*base-exception* is the optional base exception. This may be either one of +the standard Python exceptions or one defined with a previous +:directive:`%Exception` directive. + +*header-code* is the optional :directive:`%TypeHeaderCode` used to specify any +external interface to the exception being defined. + +*raise-code* is the :directive:`%RaiseCode` used to specify the handwritten +code that converts a reference to the C++ exception to the Python exception. + +For example:: + + %Exception std::exception(SIP_Exception) /PyName=StdException/ + { + %TypeHeaderCode + #include <exception> + %End + %RaiseCode + const char *detail = sipExceptionRef.what(); + + SIP_BLOCK_THREADS + PyErr_SetString(sipException_std_exception, detail); + SIP_UNBLOCK_THREADS + %End + }; + +In this example we map the standard C++ exception to a new Python exception. +The new exception is called ``StdException`` and is derived from the standard +Python exception ``Exception``. + +An exception may be annotated with :xanno:`Default` to specify that it should +be caught by default if there is no ``throw`` clause. + + +.. directive:: %ExportedDoc + +.. parsed-literal:: + + %ExportedDoc + *text* + %End + +This directive is used to specify some arbitrary text that will be extracted +by SIP when the ``-d`` command line option is used. The directive can be +specified any number of times and SIP will concatenate all the separate pieces +of text in the order that it sees them. + +Documentation that is specified using this directive will also be included by +modules that :directive:`%Import` it. + +For example:: + + %ExportedDoc + ========== + An Example + ========== + + This fragment of documentation is reStructuredText and will appear in the + module in which it is defined and all modules that %Import it. + %End + + +.. directive:: %ExportedHeaderCode + +.. parsed-literal:: + + %ExportedHeaderCode + *code* + %End + +This directive is used to specify handwritten code, typically the declarations +of types, that is placed in a header file that is included by all generated +code for all modules. It should not include function declarations because +Python modules should not explicitly call functions in another Python module. + +See also :directive:`%ModuleCode` and :directive:`%ModuleHeaderCode`. + + +.. directive:: %Feature + +.. parsed-literal:: + + %Feature *name* + +This directive is used to declare a feature. Features (along with +:directive:`%Platforms` and :directive:`%Timeline`) are used by the +:directive:`%If` directive to control whether or not parts of a specification +are processed or ignored. + +Features are mutually independent of each other - any combination of features +may be enabled or disable. By default all features are enabled. The SIP +``-x`` command line option is used to disable a feature. + +If a feature is enabled then SIP will automatically generate a corresponding C +preprocessor symbol for use by handwritten code. The symbol is the name of +the feature prefixed by ``SIP_FEATURE_``. + +For example:: + + %Feature FOO_SUPPORT + + %If (FOO_SUPPORT) + void foo(); + %End + + +.. directive:: %GCClearCode + +.. parsed-literal:: + + %GCClearCode + *code* + %End + +Python has a cyclic garbage collector which can identify and release unneeded +objects even when their reference counts are not zero. If a wrapped C +structure or C++ class keeps its own reference to a Python object then, if the +garbage collector is to do its job, it needs to provide some handwritten code +to traverse and potentially clear those embedded references. + +See the section *Supporting cyclic garbage collection* in `Embedding and +Extending the Python Interpreter <http://www.python.org/dev/doc/devel/ext/>`__ +for the details. + +This directive is used to specify the code that clears any embedded references. +(See :directive:`%GCTraverseCode` for specifying the code that traverses any +embedded references.) + +The following variables are made available to the handwritten code: + +*type* \*sipCpp + This is a pointer to the structure or class instance. Its *type* is a + pointer to the structure or class. + +int sipRes + The handwritten code should set this to the result to be returned. + +The following simplified example is taken from PyQt. The ``QCustomEvent`` +class allows arbitary data to be attached to the event. In PyQt this data is +always a Python object and so should be handled by the garbage collector:: + + %GCClearCode + PyObject *obj; + + // Get the object. + obj = reinterpret_cast<PyObject *>(sipCpp->data()); + + // Clear the pointer. + sipCpp->setData(0); + + // Clear the reference. + Py_XDECREF(obj); + + // Report no error. + sipRes = 0; + %End + + +.. directive:: %GCTraverseCode + +.. parsed-literal:: + + %GCTraverseCode + *code* + %End + +This directive is used to specify the code that traverses any embedded +references for Python's cyclic garbage collector. (See +:directive:`%GCClearCode` for a full explanation.) + +The following variables are made available to the handwritten code: + +*type* \*sipCpp + This is a pointer to the structure or class instance. Its *type* is a + pointer to the structure or class. + +visitproc sipVisit + This is the visit function provided by the garbage collector. + +void \*sipArg + This is the argument to the visit function provided by the garbage + collector. + +int sipRes + The handwritten code should set this to the result to be returned. + +The following simplified example is taken from PyQt's ``QCustomEvent`` class:: + + %GCTraverseCode + PyObject *obj; + + // Get the object. + obj = reinterpret_cast<PyObject *>(sipCpp->data()); + + // Call the visit function if there was an object. + if (obj) + sipRes = sipVisit(obj, sipArg); + else + sipRes = 0; + %End + + +.. directive:: %GetCode + +.. parsed-literal:: + + %GetCode + *code* + %End + +This directive is used after the declaration of a C++ class variable or C +structure member to specify handwritten code to convert it to a Python object. +It is usually used to handle types that SIP cannot deal with automatically. + +The following variables are made available to the handwritten code: + +*type* \*sipCpp + This is a pointer to the structure or class instance. Its *type* is a + pointer to the structure or class. It is not made available if the + variable being wrapped is a static class variable. + +PyObject \*sipPy + The handwritten code must set this to the Python representation of the + class variable or structure member. If there is an error then the code + must raise an exception and set this to ``NULL``. + +PyObject \*sipPyType + If the variable being wrapped is a static class variable then this is the + Python type object of the class from which the variable was referenced + (*not* the class in which it is defined). It may be safely cast to a + PyTypeObject \* or a sipWrapperType \*. + +For example:: + + struct Entity + { + /* + * In this contrived example the C library we are wrapping actually + * defines this as char buffer[100] which SIP cannot handle + * automatically. + */ + char *buffer; + %GetCode + sipPy = PyString_FromStringAndSize(sipCpp->buffer, 100); + %End + %SetCode + char *ptr; + int length; + + if (PyString_AsStringAndSize(sipPy, &ptr, &length) == -1) + sipErr = 1; + else if (length != 100) + { + /* + * Raise an exception because the length isn't exactly right. + */ + + PyErr_SetString(PyExc_ValueError, "an Entity.buffer must be exactly 100 bytes"); + sipErr = 1; + } + else + memcpy(sipCpp->buffer, ptr, 100); + %End + } + + +.. directive:: %If + +.. parsed-literal:: + + %If (*expression*) + *specification* + %End + +where + +.. parsed-literal:: + + *expression* ::= [*ored-qualifiers* | *range*] + + *ored-qualifiers* ::= [*qualifier* | *qualifier* **||** *ored-qualifiers*] + + *qualifier* ::= [**!**] [*feature* | *platform*] + + *range* ::= [*version*] **-** [*version*] + +This directive is used in conjunction with features (see +:directive:`%Feature`), platforms (see :directive:`%Platforms`) and versions +(see :directive:`%Timeline`) to control whether or not parts of a specification +are processed or not. + +A *range* of versions means all versions starting with the lower bound up to +but excluding the upper bound. If the lower bound is omitted then it is +interpreted as being before the earliest version. If the upper bound is +omitted then it is interpreted as being after the latest version. + +For example:: + + %Feature SUPPORT_FOO + %Platforms {WIN32_PLATFORM POSIX_PLATFORM MACOS_PLATFORM} + %Timeline {V1_0 V1_1 V2_0 V3_0} + + %If (!SUPPORT_FOO) + // Process this if the SUPPORT_FOO feature is disabled. + %End + + %If (POSIX_PLATFORM || MACOS_PLATFORM) + // Process this if either the POSIX_PLATFORM or MACOS_PLATFORM + // platforms are enabled. + %End + + %If (V1_0 - V2_0) + // Process this if either V1_0 or V1_1 is enabled. + %End + + %If (V2_0 - ) + // Process this if either V2_0 or V3_0 is enabled. + %End + + %If ( - ) + // Always process this. + %End + +Note that this directive is not implemented as a preprocessor. Only the +following parts of a specification are affected by it: + + - :directive:`%API` + - ``class`` + - :directive:`%ConvertFromTypeCode` + - :directive:`%ConvertToSubClassCode` + - :directive:`%ConvertToTypeCode` + - ``enum`` + - :directive:`%DefaultEncoding` + - :directive:`%DefaultMetatype` + - :directive:`%DefaultSupertype` + - :directive:`%ExportedHeaderCode` + - functions + - :directive:`%GCClearCode` + - :directive:`%GCTraverseCode` + - :directive:`%If` + - :directive:`%InitialisationCode` + - :directive:`%MappedType` + - :directive:`%MethodCode` + - :directive:`%ModuleCode` + - :directive:`%ModuleHeaderCode` + - ``namespace`` + - :directive:`%PostInitialisationCode` + - :directive:`%PreInitialisationCode` + - ``struct`` + - ``typedef`` + - :directive:`%TypeCode` + - :directive:`%TypeHeaderCode` + - :directive:`%UnitCode` + - variables + - :directive:`%VirtualCatcherCode` + +Also note that the only way to specify the logical and of qualifiers is to use +nested :directive:`%If` directives. + + +.. directive:: %Import + +.. parsed-literal:: + + %Import *filename* + +This directive is used to import the specification of another module. This is +needed if the current module makes use of any types defined in the imported +module, e.g. as an argument to a function, or to sub-class. + +If *filename* cannot be opened then SIP prepends *filename* with the name of +the directory containing the current specification file (i.e. the one +containing the :directive:`%Import` directive) and tries again. If this also +fails then SIP prepends *filename* with each of the directories, in turn, +specified by the ``-I`` command line option. + +For example:: + + %Import qt/qtmod.sip + + +.. directive:: %Include + +.. parsed-literal:: + + %Include *filename* + +This directive is used to include contents of another file as part of the +specification of the current module. It is the equivalent of the C +preprocessor's ``#include`` directive and is used to structure a large module +specification into manageable pieces. + +:directive:`%Include` follows the same search process as :directive:`%Import` +when trying to open *filename*. + +For example:: + + %Include qwidget.sip + + +.. directive:: %InitialisationCode + +.. parsed-literal:: + + %InitialisationCode + *code* + %End + +This directive is used to specify handwritten code that is embedded in-line +in the generated module initialisation code after the SIP module has been +imported but before the module itself has been initialised. + +It is typically used to call :cfunc:`sipRegisterPyType()`. + +For example:: + + %InitialisationCode + // The code will be executed when the module is first imported, after + // the SIP module has been imported, but before other module-specific + // initialisation has been completed. + %End + + +.. directive:: %License + +.. parsed-literal:: + + %License /*license-annotations*/ + +This directive is used to specify the contents of an optional license +dictionary. The license dictionary is called :data:`__license__` and is stored +in the module dictionary. The elements of the dictionary are specified using +the :lanno:`Licensee`, :lanno:`Signature`, :lanno:`Timestamp` and :lanno:`Type` +annotations. Only the :lanno:`Type` annotation is compulsory. + +Note that this directive isn't an attempt to impose any licensing restrictions +on a module. It is simply a method for easily embedding licensing information +in a module so that it is accessible to Python scripts. + +For example:: + + %License /Type="GPL"/ + + +.. directive:: %MappedType + +.. parsed-literal:: + + template<*type-list*> + %MappedType *type* + { + [*header-code*] + [*convert-to-code*] + [*convert-from-code*] + }; + + %MappedType *type* + { + [*header-code*] + [*convert-to-code*] + [*convert-from-code*] + }; + +This directive is used to define an automatic mapping between a C or C++ type +and a Python type. It can be used as part of a template, or to map a specific +type. + +When used as part of a template *type* cannot itself refer to a template. Any +occurrences of any of the type names (but not any ``*`` or ``&``) in +*type-list* will be replaced by the actual type names used when the template is +instantiated. Template mapped types are instantiated automatically as required +(unlike template classes which are only instantiated using ``typedef``). + +Any explicit mapped type will be used in preference to any template that maps +the same type, ie. a template will not be automatically instantiated if there +is an explicit mapped type. + +*header-code* is the :directive:`%TypeHeaderCode` used to specify the library +interface to the type being mapped. + +*convert-to-code* is the :directive:`%ConvertToTypeCode` used to specify the +handwritten code that converts a Python object to an instance of the mapped +type. + +*convert-from-code* is the :directive:`%ConvertFromTypeCode` used to specify +the handwritten code that converts an instance of the mapped type to a Python +object. + +For example:: + + template<Type *> + %MappedType QList + { + %TypeHeaderCode + // Include the library interface to the type being mapped. + #include <qlist.h> + %End + + %ConvertToTypeCode + // See if we are just being asked to check the type of the Python + // object. + if (sipIsErr == NULL) + { + // Check it is a list. + if (!PyList_Check(sipPy)) + return 0; + + // Now check each element of the list is of the type we expect. + // The template is for a pointer type so we don't disallow None. + for (int i = 0; i < PyList_GET_SIZE(sipPy); ++i) + if (!sipCanConvertToType(PyList_GET_ITEM(sipPy, i), + sipType_Type, 0)) + return 0; + + return 1; + } + + // Create the instance on the heap. + QList<Type *> *ql = new QList<Type *>; + + for (int i = 0; i < PyList_GET_SIZE(sipPy); ++i) + { + // Use the SIP API to convert the Python object to the + // corresponding C++ instance. Note that we apply any ownership + // transfer to the list itself, not the individual elements. + Type *t = reinterpret_cast<Type *>(sipConvertToType( + PyList_GET_ITEM(sipPy, i), + sipType_Type, 0, 0, 0, + sipIsErr)); + + if (*sipIsErr) + { + // Tidy up. + delete ql; + + // There is nothing on the heap. + return 0; + } + + // Add the pointer to the C++ instance. + ql->append(t); + } + + // Return the instance on the heap. + *sipCppPtr = ql; + + // Apply the normal transfer. + return sipGetState(sipTransferObj); + %End + + %ConvertFromTypeCode + PyObject *l; + + // Create the Python list of the correct length. + if ((l = PyList_New(sipCpp->size())) == NULL) + return NULL; + + // Go through each element in the C++ instance and convert it to the + // corresponding Python object. + for (int i = 0; i < sipCpp->size(); ++i) + { + Type *t = sipCpp->at(i); + PyObject *tobj; + + if ((tobj = sipConvertFromType(t, sipType_Type, sipTransferObj)) == NULL) + { + // There was an error so garbage collect the Python list. + Py_DECREF(l); + return NULL; + } + + PyList_SET_ITEM(l, i, tobj); + } + + // Return the Python list. + return l; + %End + } + +Using this we can use, for example, ``QList<QObject *>`` throughout the +module's specification files (and in any module that imports this one). The +generated code will automatically map this to and from a Python list of QObject +instances when appropriate. + + +.. directive:: %MethodCode + +.. parsed-literal:: + + %MethodCode + *code* + %End + +This directive is used as part of the specification of a global function, class +method, operator, constructor or destructor to specify handwritten code that +replaces the normally generated call to the function being wrapped. It is +usually used to handle argument types and results that SIP cannot deal with +automatically. + +Normally the specified code is embedded in-line after the function's arguments +have been successfully converted from Python objects to their C or C++ +equivalents. In this case the specified code must not include any ``return`` +statements. + +However if the :fanno:`NoArgParser` annotation has been used then the specified +code is also responsible for parsing the arguments. No other code is generated +by SIP and the specified code must include a ``return`` statement. + +In the context of a destructor the specified code is embedded in-line in the +Python type's deallocation function. Unlike other contexts it supplements +rather than replaces the normally generated code, so it must not include code +to return the C structure or C++ class instance to the heap. The code is only +called if ownership of the structure or class is with Python. + +The specified code must also handle the Python Global Interpreter Lock (GIL). +If compatibility with SIP v3.x is required then the GIL must be released +immediately before the C++ call and reacquired immediately afterwards as shown +in this example fragment:: + + Py_BEGIN_ALLOW_THREADS + sipCpp->foo(); + Py_END_ALLOW_THREADS + +If compatibility with SIP v3.x is not required then this is optional but +should be done if the C++ function might block the current thread or take a +significant amount of time to execute. (See :ref:`ref-gil` and the +:fanno:`ReleaseGIL` and :fanno:`HoldGIL` annotations.) + +If the :fanno:`NoArgParser` annotation has not been used then the following +variables are made available to the handwritten code: + +*type* a0 + There is a variable for each argument of the Python signature (excluding + any ``self`` argument) named ``a0``, ``a1``, etc. The *type* of the + variable is the same as the type defined in the specification with the + following exceptions: + + - if the argument is only used to return a value (e.g. it is an ``int *`` + without an :aanno:`In` annotation) then the type has one less level of + indirection (e.g. it will be an ``int``) + - if the argument is a structure or class (or a reference or a pointer to a + structure or class) then *type* will always be a pointer to the structure + or class. + + Note that handwritten code for destructors never has any arguments. + +PyObject \*a0Wrapper + This variable is made available only if the :aanno:`GetWrapper` annotation + is specified for the corresponding argument. The variable is a pointer to + the Python object that wraps the argument. + +*type* \*sipCpp + If the directive is used in the context of a class constructor then this + must be set by the handwritten code to the constructed instance. If it is + set to ``0`` and no Python exception is raised then SIP will continue to + try other Python signatures. + + If the directive is used in the context of a method (but not the standard + binary operator methods, e.g. :meth:`__add__`) or a destructor then this is + a pointer to the C structure or C++ class instance. + + Its *type* is a pointer to the structure or class. + + Standard binary operator methods follow the same convention as global + functions and instead define two arguments called ``a0`` and ``a1``. + +sipErrorState sipError + The handwritten code should set this to either ``sipErrorContinue`` or + ``sipErrorFail``, and raise an appropriate Python exception, if an error + is detected. Its initial value will be ``sipErrorNone``. + + When ``sipErrorContinue`` is used, SIP will remember the exception as the + reason why the particular overloaded callable could not be invoked. It + will then continue to try the next overloaded callable. It is typically + used by code that needs to do additional type checking of the callable's + arguments. + + When ``sipErrorFail1`` is used, SIP will report the exception immediately + and will not attempt to invoke other overloaded callables. + + ``sipError`` is not provided for destructors. + +int sipIsErr + The handwritten code should set this to a non-zero value, and raise an + appropriate Python exception, if an error is detected. This is the + equivalent of setting ``sipError`` to ``sipErrorFail``. Its initial value + will be ``0``. + + ``sipIsErr`` is not provided for destructors. + +*type* sipRes + The handwritten code should set this to the result to be returned. The + *type* of the variable is the same as the type defined in the Python + signature in the specification with the following exception: + + - if the argument is a structure or class (or a reference or a pointer to a + structure or class) then *type* will always be a pointer to the structure + or class. + + ``sipRes`` is not provided for inplace operators (e.g. ``+=`` or + :meth:`__imul__`) as their results are handled automatically, nor for class + constructors or destructors. + +PyObject \*sipSelf + If the directive is used in the context of a class constructor, destructor + or method then this is the Python object that wraps the structure or class + instance, i.e. ``self``. + +bool sipSelfWasArg + This is only made available for non-abstract, virtual methods. It is set + if ``self`` was explicitly passed as the first argument of the method + rather than being bound to the method. In other words, the call was:: + + Klass.foo(self, ...) + + rather than:: + + self.foo(...) + +If the :fanno:`NoArgParser` annotation has been used then only the following +variables are made available to the handwritten code: + +PyObject \*sipArgs + This is the tuple of arguments. + +PyObject \*sipKwds + This is the dictionary of keyword arguments. + +The following is a complete example:: + + class Klass + { + public: + virtual int foo(SIP_PYTUPLE); + %MethodCode + // The C++ API takes a 2 element array of integers but passing a + // two element tuple is more Pythonic. + + int iarr[2]; + + if (PyArg_ParseTuple(a0, "ii", &iarr[0], &iarr[1])) + { + Py_BEGIN_ALLOW_THREADS + sipRes = sipSelfWasArg ? sipCpp->Klass::foo(iarr) + : sipCpp->foo(iarr); + Py_END_ALLOW_THREADS + } + else + { + // PyArg_ParseTuple() will have raised the exception. + sipIsErr = 1; + } + %End + }; + +As the example is a virtual method [#]_, note the use of ``sipSelfWasArg`` to +determine exactly which implementation of ``foo()`` to call. + +If a method is in the ``protected`` section of a C++ class then SIP generates +helpers that provide access to method. However, these are not available if +the Python module is being built with ``protected`` redefined as ``public``. + +The following pattern should be used to cover all possibilities:: + + #if defined(SIP_PROTECTED_IS_PUBLIC) + sipRes = sipSelfWasArg ? sipCpp->Klass::foo(iarr) + : sipCpp->foo(iarr); + #else + sipRes = sipCpp->sipProtectVirt_foo(sipSelfWasArg, iarr); + #endif + +If a method is in the ``protected`` section of a C++ class but is not virtual +then the pattern should instead be:: + + #if defined(SIP_PROTECTED_IS_PUBLIC) + sipRes = sipCpp->foo(iarr); + #else + sipRes = sipCpp->sipProtect_foo(iarr); + #endif + +.. [#] See :directive:`%VirtualCatcherCode` for a description of how SIP + generated code handles the reimplementation of C++ virtual methods in + Python. + + +.. directive:: %Module + +.. parsed-literal:: + + %Module *name* [*version*] + +This directive is used to identify that the library being wrapped is a C++ +library and to define the name of the module and it's optional version number. + +The name may contain periods to specify that the module is part of a Python +package. + +The optional version number is useful if you (or others) might create other +modules that build on this module, i.e. if another module might +:directive:`%Import` this module. Under the covers, a module exports an API +that is used by modules that :directive:`%Import` it and the API is given a +version number. A module built on that module knows the version number of the +API that it is expecting. If, when the modules are imported at run-time, the +version numbers do not match then a Python exception is raised. The dependent +module must then be re-built using the correct specification files for the base +module. + +The version number should be incremented whenever a module is changed. Some +changes don't affect the exported API, but it is good practice to change the +version number anyway. + +For example:: + + %Module qt 5 + + +.. directive:: %ModuleCode + +.. parsed-literal:: + + %ModuleCode + *code* + %End + +This directive is used to specify handwritten code, typically the +implementations of utility functions, that can be called by other handwritten +code in the module. + +For example:: + + %ModuleCode + // Print an object on stderr for debugging purposes. + void dump_object(PyObject *o) + { + PyObject_Print(o, stderr, 0); + fprintf(stderr, "\n"); + } + %End + +See also :directive:`%ExportedHeaderCode` and :directive:`%ModuleHeaderCode`. + + +.. directive:: %ModuleHeaderCode + +.. parsed-literal:: + + %ModuleHeaderCode + *code* + %End + +This directive is used to specify handwritten code, typically the declarations +of utility functions, that is placed in a header file that is included by all +generated code for the same module. + +For example:: + + %ModuleHeaderCode + void dump_object(PyObject *o); + %End + +See also :directive:`%ExportedHeaderCode` and :directive:`%ModuleCode`. + + +.. directive:: %OptionalInclude + +.. parsed-literal:: + + %OptionalInclude *filename* + +This directive is identical to the :directive:`%Include` directive except that +SIP silently continues processing if *filename* could not be opened. + +For example:: + + %OptionalInclude license.sip + + +.. directive:: %PickleCode + +.. parsed-literal:: + + %PickleCode + *code* + %End + +This directive is used to specify handwritten code to pickle a C structure or +C++ class instance. + +The following variables are made available to the handwritten code: + +*type* \*sipCpp + This is a pointer to the structure or class instance. Its *type* is a + pointer to the structure or class. + +PyObject \*sipRes + The handwritten code must set this to a tuple of the arguments that will + be passed to the type's __init__() method when the structure or class + instance is unpickled. If there is an error then the code must raise an + exception and set this to ``NULL``. + +For example:: + + class Point + { + Point(int x, y); + + int x() const; + int y() const; + + %PickleCode + sipRes = Py_BuildValue("ii", sipCpp->x(), sipCpp->y()); + %End + } + +Note that SIP works around the Python limitation that prevents nested types +being pickled. + +Both named and unnamed enums can be pickled automatically without providing any +handwritten code. + + +.. directive:: %Platforms + +.. parsed-literal:: + + %Platforms {*name* *name* ...} + +This directive is used to declare a set of platforms. Platforms (along with +:directive:`%Feature` and :directive:`%Timeline`) are used by the +:directive:`%If` directive to control whether or not parts of a specification +are processed or ignored. + +Platforms are mutually exclusive - only one platform can be enabled at a time. +By default all platforms are disabled. The SIP ``-t`` command line option is +used to enable a platform. + +For example:: + + %Platforms {WIN32_PLATFORM POSIX_PLATFORM MACOS_PLATFORM} + + %If (WIN32_PLATFORM) + void undocumented(); + %End + + %If (POSIX_PLATFORM) + void documented(); + %End + + +.. directive:: %PostInitialisationCode + +.. parsed-literal:: + + %PostInitialisationCode + *code* + %End + +This directive is used to specify handwritten code that is embedded in-line +at the very end of the generated module initialisation code. + +The following variables are made available to the handwritten code: + +PyObject \*sipModule + This is the module object returned by ``Py_InitModule()``. + +PyObject \*sipModuleDict + This is the module's dictionary object returned by ``Py_ModuleGetDict()``. + +For example:: + + %PostInitialisationCode + // The code will be executed when the module is first imported and + // after all other initialisation has been completed. + %End + + +.. directive:: %PreInitialisationCode + +.. parsed-literal:: + + %PreInitialisationCode + *code* + %End + +This directive is used to specify handwritten code that is embedded in-line +at the very start of the generated module initialisation code. + +For example:: + + %PreInitialisationCode + // The code will be executed when the module is first imported and + // before other initialisation has been completed. + %End + + +.. directive:: %RaiseCode + +.. parsed-literal:: + + %RaiseCode + *code* + %End + +This directive is used as part of the definition of an exception using the +:directive:`%Exception` directive to specify handwritten code that raises a +Python exception when a C++ exception has been caught. The code is embedded +in-line as the body of a C++ ``catch ()`` clause. + +The specified code must handle the Python Global Interpreter Lock (GIL) if +necessary. The GIL must be acquired before any calls to the Python API and +released after the last call as shown in this example fragment:: + + SIP_BLOCK_THREADS + PyErr_SetNone(PyErr_Exception); + SIP_UNBLOCK_THREADS + +Finally, the specified code must not include any ``return`` statements. + +The following variable is made available to the handwritten code: + +*type* &sipExceptionRef + This is a reference to the caught C++ exception. The *type* of the + reference is the same as the type defined in the ``throw ()`` specifier. + +See the :directive:`%Exception` directive for an example. + + +.. directive:: %SetCode + +.. parsed-literal:: + + %SetCode + *code* + %End + +This directive is used after the declaration of a C++ class variable or C +structure member to specify handwritten code to convert it from a Python +object. It is usually used to handle types that SIP cannot deal with +automatically. + +The following variables are made available to the handwritten code: + +*type* \*sipCpp + This is a pointer to the structure or class instance. Its *type* is a + pointer to the structure or class. It is not made available if the + variable being wrapped is a static class variable. + +int sipErr + If the conversion failed then the handwritten code should raise a Python + exception and set this to a non-zero value. Its initial value will be + automatically set to zero. + +PyObject \*sipPy + This is the Python object that the handwritten code should convert. + +PyObject \*sipPyType + If the variable being wrapped is a static class variable then this is the + Python type object of the class from which the variable was referenced + (*not* the class in which it is defined). It may be safely cast to a + PyTypeObject \* or a sipWrapperType \*. + +See the :directive:`%GetCode` directive for an example. + + +.. directive:: %Timeline + +.. parsed-literal:: + + %Timeline {*name* *name* ...} + +This directive is used to declare a set of versions released over a period of +time. Versions (along with :directive:`%Feature` and :directive:`%Platforms`) +are used by the :directive:`%If` directive to control whether or not parts of a +specification are processed or ignored. + +Versions are mutually exclusive - only one version can be enabled at a time. +By default all versions are disabled. The SIP ``-t`` command line option is +used to enable a version. + +For example:: + + %Timeline {V1_0 V1_1 V2_0 V3_0} + + %If (V1_0 - V2_0) + void foo(); + %End + + %If (V2_0 -) + void foo(int = 0); + %End + +:directive:`%Timeline` can be used any number of times in a module to allow +multiple libraries to be wrapped in the same module. + + +.. directive:: %TypeCode + +.. parsed-literal:: + + %TypeCode + *code* + %End + +This directive is used as part of the specification of a C structure or a C++ +class to specify handwritten code, typically the implementations of utility +functions, that can be called by other handwritten code in the structure or +class. + +For example:: + + class Klass + { + %TypeCode + // Print an instance on stderr for debugging purposes. + static void dump_klass(const Klass *k) + { + fprintf(stderr,"Klass %s at %p\n", k->name(), k); + } + %End + + // The rest of the class specification. + + }; + +Because the scope of the code is normally within the generated file that +implements the type, any utility functions would normally be declared +``static``. However a naming convention should still be adopted to prevent +clashes of function names within a module in case the SIP ``-j`` command line +option is used. + + +.. directive:: %TypeHeaderCode + +.. parsed-literal:: + + %TypeHeaderCode + *code* + %End + +This directive is used to specify handwritten code that defines the interface +to a C or C++ type being wrapped, either a structure, a class, or a template. +It is used within a class definition or a :directive:`%MappedType` directive. + +Normally *code* will be a pre-processor ``#include`` statement. + +For example:: + + // Wrap the Klass class. + class Klass + { + %TypeHeaderCode + #include <klass.h> + %End + + // The rest of the class specification. + }; + + +.. directive:: %UnitCode + +.. parsed-literal:: + + %UnitCode + *code* + %End + +This directive is used to specify handwritten code that it included at the very +start of a generated compilation unit (ie. C or C++ source file). It is +typically used to ``#include`` a C++ precompiled header file. + + +.. directive:: %VirtualCatcherCode + +.. parsed-literal:: + + %VirtualCatcherCode + *code* + %End + +For most classes there are corresponding :ref:`generated derived classes +<ref-derived-classes>` that contain reimplementations of the class's virtual +methods. These methods (which SIP calls catchers) determine if there is a +corresponding Python reimplementation and call it if so. If there is no Python +reimplementation then the method in the original class is called instead. + +This directive is used to specify handwritten code that replaces the normally +generated call to the Python reimplementation and the handling of any returned +results. It is usually used to handle argument types and results that SIP +cannot deal with automatically. + +This directive can also be used in the context of a class destructor to +specify handwritten code that is embedded in-line in the internal derived +class's destructor. + +In the context of a method the Python Global Interpreter Lock (GIL) is +automatically acquired before the specified code is executed and automatically +released afterwards. + +In the context of a destructor the specified code must handle the GIL. The +GIL must be acquired before any calls to the Python API and released after the +last call as shown in this example fragment:: + + SIP_BLOCK_THREADS + Py_DECREF(obj); + SIP_UNBLOCK_THREADS + +The following variables are made available to the handwritten code in the +context of a method: + +*type* a0 + There is a variable for each argument of the C++ signature named ``a0``, + ``a1``, etc. The *type* of the variable is the same as the type defined in + the specification. + +int a0Key + There is a variable for each argument of the C++ signature that has a type + where it is important to ensure that the corresponding Python object is not + garbage collected too soon. This only applies to output arguments that + return ``'\0'`` terminated strings. The variable would normally be passed + to :cfunc:`sipParseResult()` using either the ``A`` or ``B`` format + characters. + +int sipIsErr + The handwritten code should set this to a non-zero value, and raise an + appropriate Python exception, if an error is detected. + +PyObject \*sipMethod + This object is the Python reimplementation of the virtual C++ method. It + is normally passed to :cfunc:`sipCallMethod()`. + +*type* sipRes + The handwritten code should set this to the result to be returned. The + *type* of the variable is the same as the type defined in the C++ signature + in the specification. + +int sipResKey + This variable is only made available if the result has a type where it is + important to ensure that the corresponding Python object is not garbage + collected too soon. This only applies to ``'\0'`` terminated strings. The + variable would normally be passed to :cfunc:`sipParseResult()` using either + the ``A`` or ``B`` format characters. + +sipSimpleWrapper \*sipPySelf + This variable is only made available if either the ``a0Key`` or + ``sipResKey`` are made available. It defines the context within which keys + are unique. The variable would normally be passed to + :cfunc:`sipParseResult()` using the ``S`` format character. + +No variables are made available in the context of a destructor. + +For example:: + + class Klass + { + public: + virtual int foo(SIP_PYTUPLE) [int (int *)]; + %MethodCode + // The C++ API takes a 2 element array of integers but passing a + // two element tuple is more Pythonic. + + int iarr[2]; + + if (PyArg_ParseTuple(a0, "ii", &iarr[0], &iarr[1])) + { + Py_BEGIN_ALLOW_THREADS + sipRes = sipCpp->Klass::foo(iarr); + Py_END_ALLOW_THREADS + } + else + { + // PyArg_ParseTuple() will have raised the exception. + sipIsErr = 1; + } + %End + %VirtualCatcherCode + // Convert the 2 element array of integers to the two element + // tuple. + + PyObject *result; + + result = sipCallMethod(&sipIsErr, sipMethod, "ii", a0[0], a0[1]); + + if (result != NULL) + { + // Convert the result to the C++ type. + sipParseResult(&sipIsErr, sipMethod, result, "i", &sipRes); + + Py_DECREF(result); + } + %End + }; diff --git a/sphinx/distutils.rst b/sphinx/distutils.rst new file mode 100644 index 0000000..21a6b36 --- /dev/null +++ b/sphinx/distutils.rst @@ -0,0 +1,41 @@ +.. _ref-distutils: + +Building Your Extension with distutils +====================================== + +To build the example in :ref:`ref-simple-c++-example` using distutils, it is +sufficient to create a standard ``setup.py``, listing ``word.sip`` among the +files to build, and hook-up SIP into distutils:: + + from distutils.core import setup, Extension + import sipdistutils + + setup( + name = 'word', + versione = '1.0', + ext_modules=[ + Extension("word", ["word.sip", "word.cpp"]), + ], + + cmdclass = {'build_ext': sipdistutils.build_ext} + ) + +As we can see, the above is a normal distutils setup script, with just a +special line which is needed so that SIP can see and process ``word.sip``. +Then, running ``setup.py build`` will build our extension module. + +If you want to use any of sip's command-line options described in +:ref:`ref-command-line`, there is a new option available for the +``build_ext`` command in distutils: ``--sip-opts``. So you can either invoke +distutils as follows:: + + $ python setup.py build_ext --sip-opts="-e -g" build + +or you can leverage distutils' config file support by creating a ``setup.cfg`` +file in the supported system or local paths (eg: in the same directory of +``setup.py``) with these contents:: + + [build_ext] + sip-opts = -e -g + +and then run ``setup.py build`` as usual. diff --git a/sphinx/embedding.rst b/sphinx/embedding.rst new file mode 100644 index 0000000..114e3e8 --- /dev/null +++ b/sphinx/embedding.rst @@ -0,0 +1,62 @@ +Using the C API when Embedding +============================== + +The :ref:`C API <ref-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 or +C++ applications that embed the Python interpreter and need to pass C or C++ +instances between the application and the interpreter. + +The API is exported by the SIP module as a ``sipAPIDef`` data structure +containing a set of function pointers. The data structure is defined in the +SIP header file ``sip.h``. The data structure is wrapped as a Python +``PyCObject`` object and is referenced by the name ``_C_API`` in the SIP +module dictionary. + +Each member of the data structure is a pointer to one of the functions of the +SIP 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 objects that SIP generates for a wrapped module (see +:ref:`ref-type-structures`, :ref:`ref-enum-type-objects` and +:ref:`ref-exception-objects`) cannot be refered to directly and must be +obtained using the :cfunc:`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() + { + PyObject *sip_module; + PyObject *sip_module_dict; + PyObject *c_api; + + /* Import the SIP module. */ + sip_module = PyImport_ImportModule("sip"); + + if (sip_module == NULL) + return NULL; + + /* Get the module's dictionary. */ + sip_module_dict = PyModule_GetDict(sip_module); + + /* Get the "_C_API" attribute. */ + c_api = PyDict_GetItemString(sip_module_dict, "_C_API"); + + if (c_api == NULL) + return NULL; + + /* Sanity check that it is the right type. */ + if (!PyCObject_Check(c_api)) + return NULL; + + /* Get the actual pointer from the object. */ + return (const sipAPIDef *)PyCObject_AsVoidPtr(c_api); + } diff --git a/sphinx/incompatibilities.rst b/sphinx/incompatibilities.rst new file mode 100644 index 0000000..a006e4f --- /dev/null +++ b/sphinx/incompatibilities.rst @@ -0,0 +1,198 @@ +Potential Incompatibilities with Earlier Versions +================================================= + +This section describes incompatibilities introduced by particular versions of +SIP. Normally these are the removal of previously deprecated features. + + +SIP v4.10.1 +----------- + +Newly Deprecated Features +************************* + +The following parts of the :ref:`C API <ref-c-api>` are now deprecated (but +still supported). + +- The ``D`` format character of :cfunc:`sipParseResult()`. + + +SIP v4.8 +-------- + +__truediv__ +*********** + +Prior to this version the :meth:`__div__` special method implicitly defined the +:meth:`__truediv__` special method. From this version the :meth:`__truediv__` +special method must be explicitly defined. + + +sipWrapper user Member +********************** + +Prior to this version the :ctype:`sipWrapper` structure had a member called +:ctype:`user` which is available for handwritten code to use. From this +version :ctype:`user` is a member of the :ctype:`sipSimpleWrapper` structure. + +:ctype:`sipWrapper` pointers can be safely cast to :ctype:`sipSimpleWrapper` +pointers, so if your code does something like:: + + ((sipWrapper *)obj)->user = an_object_reference; + +then you just need to change it to:: + + ((sipSimpleWrapper *)obj)->user = an_object_reference; + + +Removal of Previously Deprecated Features +***************************************** + +The following parts of the :ref:`C API <ref-c-api>` have been removed. + +- The ``a``, ``A``, ``M``, ``N``, ``O``, ``P`` and ``T`` format characters + from :cfunc:`sipBuildResult()` and :cfunc:`sipCallMethod()`. + +- The ``a``, ``A``, ``L`` and ``M`` format characters from + :cfunc:`sipParseResult()`. + +- :cfunc:`sipConvertToCpp()` + +- :cfunc:`sipIsSubClassInstance()` + +- :cfunc:`sipTransfer()` + +- The :func:`transfer` function of the :mod:`sip` module. + +- The old-style generated type convertors. + +In addition the :option:`-a` command line option to :file:`configure.py` has +been removed. + + +Removal of PyQt-specific Features +********************************* + +The following PyQt-specific support functions have been removed. + +- :cfunc:`sipConnectRx()` + +- :cfunc:`sipDisconnectRx()` + +- :cfunc:`sipEmitSlot()` + +- :cfunc:`sipGetSender()` + + +Newly Deprecated Features +************************* + +The following parts of the :ref:`C API <ref-c-api>` are now deprecated (but +still supported). + +- The :ref:`ref-type-objects`. + +- The :ref:`ref-enum-type-objects`. + +- :cfunc:`sipConvertFromInstance()` + +- :cfunc:`sipConvertFromMappedType()` + +- :cfunc:`sipConvertFromNamedEnum()` + +- :cfunc:`sipConvertFromNewInstance()` + +- :cfunc:`sipCanConvertToInstance()` + +- :cfunc:`sipCanConvertToMappedType()` + +- :cfunc:`sipConvertToInstance()` + +- :cfunc:`sipConvertToMappedType()` + +- :cfunc:`sipForceConvertToInstance()` + +- :cfunc:`sipForceConvertToMappedType()` + +- :cfunc:`sipClassName()` + +- :cfunc:`sipFindClass()` + +- :cfunc:`sipFindNamedEnum()` + +- :cfunc:`sipFindMappedType()` + +- :cfunc:`sipGetWrapper()` + +- :cfunc:`sipReleaseInstance()` + +- :cfunc:`sipReleaseMappedType()` + +- :cfunc:`sipWrapper_Check()` + +- The ``B``, ``C`` and ``E`` format characters of :cfunc:`sipBuildResult()` and + :cfunc:`sipCallMethod()`. + +- The ``s``, ``C`` and ``E`` format characters of :cfunc:`sipParseResult()`. + + +SIP v4.7.8 +---------- + +Automatic int to Enum Conversions +********************************* + +This version allows a Python ``int`` object to be passed whenever an enum is +expected. This can mean that two signatures that were different with prior +versions are now the same as far as Python is concerned. + +The :aanno:`Constrained` argument annotation can now be applied to an enum +argument to revert to the earlier behaviour. + + +SIP v4.7.3 +---------- + +Complementary Comparison Operators +********************************** + +Prior to this version SIP did not automatically generate missing complementary +comparison operators. Typically this was worked around by adding them +explicitly to the .sip files, even though they weren't implemented in C++ and +relied on the C++ compiler calling the complementary operator that was +implemented. + +A necessary change to the code generator meant that this not longer worked and +so SIP was changed to automatically generate any missing complementary +operators. If you have added such operators explicitly then you should remove +them or make them dependent on the particular version of SIP. + + +SIP v4.4 +-------- + +%ConvertFromTypeCode and %ConvertToTypeCode +******************************************* + +Handwritten :directive:`%ConvertFromTypeCode` and +:directive:`%ConvertToTypeCode` now have the responsibility for implementing +the :aanno:`Transfer` and :aanno:`TransferBack` annotations. + + +SIP_BUILD +********* + +The :cmacro:`SIP_BUILD` C preprocessor symbol has been removed. + + +Newly Deprecated Features +************************* + +The following parts of the :ref:`C API <ref-c-api>` are now deprecated (but +still supported). + +- The old-style generated type convertors. + +- :cfunc:`sipConvertToCpp()` + +- :cfunc:`sipIsSubClassInstance()` diff --git a/sphinx/index.rst b/sphinx/index.rst new file mode 100644 index 0000000..ac9289c --- /dev/null +++ b/sphinx/index.rst @@ -0,0 +1,20 @@ +SIP Reference Guide +=================== + +.. toctree:: + :maxdepth: 2 + + introduction + incompatibilities + installation + using + command_line + specification_files + directives + annotations + c_api + embedding + python_api + build_system + distutils + builtin diff --git a/sphinx/installation.rst b/sphinx/installation.rst new file mode 100644 index 0000000..3f9f823 --- /dev/null +++ b/sphinx/installation.rst @@ -0,0 +1,169 @@ +Installation +============ + +Downloading +----------- + +You can get the latest release of the SIP source code from +http://www.riverbankcomputing.com/software/sip/download. + +SIP is also included with all of the major Linux distributions. However, it +may be a version or two out of date. + + +Configuring +----------- + +After unpacking the source package (either a ``.tar.gz`` or a ``.zip`` file +depending on your platform) you should then check for any ``README`` files +that relate to your platform. + +Next you need to configure SIP by executing the ``configure.py`` script. For +example:: + + python configure.py + +This assumes that the Python interpreter is on your path. Something like the +following may be appropriate on Windows:: + + c:\python26\python configure.py + +If you have multiple versions of Python installed then make sure you use the +interpreter for which you wish SIP to generate bindings for. + +The full set of command line options is: + +.. program:: configure.py + +.. cmdoption:: --version + + Display the SIP version number. + +.. cmdoption:: -h, --help + + Display a help message. + +.. cmdoption:: --arch <ARCH> + + Binaries for the MacOS/X architecture ``<ARCH>`` will be built. This + option should be given once for each architecture to be built. Specifying + more than one architecture will cause a universal binary to be created. + +.. cmdoption:: -b <DIR>, --bindir <DIR> + + The SIP code generator will be installed in the directory ``<DIR>``. + +.. cmdoption:: -d <DIR>, --destdir <DIR> + + The SIP module will be installed in the directory ``<DIR>``. + +.. cmdoption:: -e <DIR>, --incdir <DIR> + + The SIP header file will be installed in the directory ``<DIR>``. + +.. cmdoption:: -k, --static + + The SIP module will be built as a static library. This is useful when + building the SIP module as a Python builtin (see :ref:`ref-builtin`). + +.. cmdoption:: -n, --universal + + The SIP code generator and module will be built as universal binaries + under MacOS/X. If the :option:`--arch <configure.py --arch>` option has + not been specified then the universal binary will include the ``i386`` and + ``ppc`` architectures. + +.. cmdoption:: -p <PLATFORM>, --platform <PLATFORM> + + Explicitly specify the platform/compiler to be used by the build system, + otherwise a platform specific default will be used. The + :option:`--show-platforms <configure.py --show-platforms>` option will + display all the supported platform/compilers. + +.. cmdoption:: -s <SDK>, --sdk <SDK> + + If the :option:`--universal <configure.py -n>` option was given then this + specifies the name of the SDK directory. If a path is not given then it is + assumed to be a sub-directory of ``/Developer/SDKs``. + +.. cmdoption:: -u, --debug + + The SIP module will be built with debugging symbols. + +.. cmdoption:: -v <DIR>, --sipdir <DIR> + + By default ``.sip`` files will be installed in the directory ``<DIR>``. + +.. cmdoption:: --show-platforms + + The list of all supported platform/compilers will be displayed. + +.. cmdoption:: --show-build-macros + + The list of all available build macros will be displayed. + +The ``configure.py`` script takes many other options that allows the build +system to be finely tuned. These are of the form ``name=value`` or +``name+=value``. The :option:`--show-build-macros <configure.py +--show-build-macros>` option will display each supported ``name``, although not +all are applicable to all platforms. + +The ``name=value`` form means that ``value`` will replace the existing value of +``name``. + +The ``name+=value`` form means that ``value`` will be appended to the existing +value of ``name``. + +For example, the following will disable support for C++ exceptions (and so +reduce the size of module binaries) when used with GCC:: + + python configure.py CXXFLAGS+=-fno-exceptions + +A pure Python module called ``sipconfig.py`` is generated by ``configure.py``. +This defines each ``name`` and its corresponding ``value``. Looking at it will +give you a good idea of how the build system uses the different options. It is +covered in detail in :ref:`ref-build-system`. + + +Configuring for MinGW +********************* + +SIP, and the modules it generates, can be built with MinGW, the Windows port of +GCC. You must use the :option:`--platform <configure.py -p>` command line +option to specify the correct platform. For example:: + + c:\python26\python configure.py --platform win32-g++ + + +Configuring for the Borland C++ Compiler +**************************************** + +SIP, and the modules it generates, can be built with the free Borland C++ +compiler. You must use the :option:`--platform <configure.py -p>` command line +option to specify the correct platform. For example:: + + c:\python26\python configure.py --platform win32-borland + +You must also make sure you have a Borland-compatible version of the Python +library. If you are using the standard Python distribution (built using the +Microsoft compiler) then you must convert the format of the Python library. +For example:: + + coff2omf python26.lib python26_bcpp.lib + + +Building +-------- + +The next step is to build SIP by running your platform's ``make`` command. For +example:: + + make + +The final step is to install SIP by running the following command:: + + make install + +(Depending on your system you may require root or administrator privileges.) + +This will install the various SIP components. diff --git a/sphinx/introduction.rst b/sphinx/introduction.rst new file mode 100644 index 0000000..8515243 --- /dev/null +++ b/sphinx/introduction.rst @@ -0,0 +1,169 @@ +Introduction +============ + +This is the reference guide for SIP 4.10.5. SIP is a tool for +automatically generating `Python <http://www.python.org>`__ bindings for C and +C++ libraries. SIP was originally developed in 1998 for +`PyQt <http://www.riverbankcomputing.com/software/pyqt>`__ - the Python +bindings for the Qt GUI toolkit - but is suitable for generating bindings for +any C or C++ library. + +This version of SIP generates bindings for Python v2.3 or later, including +Python v3. + +There are many other similar tools available. One of the original such tools +is `SWIG <http://www.swig.org>`__ and, in fact, SIP is so called because it +started out as a small SWIG. Unlike SWIG, SIP is specifically designed for +bringing together Python and C/C++ and goes to great lengths to make the +integration as tight as possible. + +The homepage for SIP is http://www.riverbankcomputing.com/software/sip. Here +you will always find the latest stable version and the latest version of this +documentation. + +SIP can also be downloaded from the +`Mercurial <http://mercurial.selenic.com/>`__ repository at +http://www.riverbankcomputing.com/hg/sip. + + +License +------- + +SIP is licensed under similar terms as Python itself. SIP is also licensed +under the GPL (both v2 and v3). It is your choice as to which license you +use. If you choose the GPL then any bindings you create must be distributed +under the terms of the GPL. + + +Features +-------- + +SIP, and the bindings it produces, have the following features: + +- bindings are fast to load and minimise memory consumption especially when + only a small sub-set of a large library is being used + +- automatic conversion between standard Python and C/C++ data types + +- overloading of functions and methods with different argument signatures + +- support for Python's keyword argument syntax + +- support for both explicitly specified and automatically generated docstrings + +- access to a C++ class's protected methods + +- the ability to define a Python class that is a sub-class of a C++ class, + including abstract C++ classes + +- Python sub-classes can implement the :meth:`__dtor__` method which will be + called from the C++ class's virtual destructor + +- support for ordinary C++ functions, class methods, static class methods, + virtual class methods and abstract class methods + +- the ability to re-implement C++ virtual and abstract methods in Python + +- support for global and class variables + +- support for global and class operators + +- support for C++ namespaces + +- support for C++ templates + +- support for C++ exceptions and wrapping them as Python exceptions + +- the automatic generation of complementary rich comparison slots + +- support for deprecation warnings + +- the ability to define mappings between C++ classes and similar Python data + types that are automatically invoked + +- the ability to automatically exploit any available run time type information + to ensure that the class of a Python instance object matches the class of the + corresponding C++ instance + +- the ability to change the type and meta-type of the Python object used to + wrap a C/C++ data type + +- full support of the Python global interpreter lock, including the ability to + specify that a C++ function of method may block, therefore allowing the lock + to be released and other Python threads to run + +- support for consolidated modules where the generated wrapper code for a + number of related modules may be included in a single, possibly private, + module + +- support for the concept of ownership of a C++ instance (i.e. what part of the + code is responsible for calling the instance's destructor) and how the + ownership may change during the execution of an application + +- the ability to generate bindings for a C++ class library that itself is built + on another C++ class library which also has had bindings generated so that + the different bindings integrate and share code properly + +- a sophisticated versioning system that allows the full lifetime of a C++ + class library, including any platform specific or optional features, to be + described in a single set of specification files + +- the ability to include documentation in the specification files which can be + extracted and subsequently processed by external tools + +- the ability to include copyright notices and licensing information in the + specification files that is automatically included in all generated source + code + +- a build system, written in Python, that you can extend to configure, compile + and install your own bindings without worrying about platform specific issues + +- support for building your extensions using distutils + +- SIP, and the bindings it produces, runs under UNIX, Linux, Windows and + MacOS/X + + +SIP Components +-------------- + +SIP comprises a number of different components. + +- The SIP code generator (:program:`sip`). This processes :file:`.sip` + specification files and generates C or C++ bindings. It is covered in detail + in :ref:`ref-using`. + +- The SIP header file (:file:`sip.h`). This contains definitions and data + structures needed by the generated C and C++ code. + +- The SIP module (:file:`sip.so` or :file:`sip.pyd`). This is a Python + extension module that is imported automatically by SIP generated bindings and + provides them with some common utility functions. See also + :ref:`ref-python-api`. + +- The SIP build system (:file:`sipconfig.py`). This is a pure Python module + that is created when SIP is configured and encapsulates all the necessary + information about your system including relevant directory names, compiler + and linker flags, and version numbers. It also includes several Python + classes and functions which help you write configuration scripts for your own + bindings. It is covered in detail in :ref:`ref-build-system`. + +- The SIP distutils extension (:file:`sipdistutils.py`). This is a distutils + extension that can be used to build your extension modules using distutils + and is an alternative to writing configuration scripts with the SIP build + system. This can be as simple as adding your .sip files to the list of files + needed to build the extension module. It is covered in detail in + :ref:`ref-distutils`. + + +Qt Support +---------- + +SIP has specific support for the creation of bindings based on Nokia's Qt +toolkit. + +The SIP code generator understands the signal/slot type safe callback mechanism +that Qt uses to connect objects together. This allows applications to define +new Python signals, and allows any Python callable object to be used as a slot. + +SIP itself does not require Qt to be installed. 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. diff --git a/sphinx/specification_files.rst b/sphinx/specification_files.rst new file mode 100644 index 0000000..6ba3aba --- /dev/null +++ b/sphinx/specification_files.rst @@ -0,0 +1,499 @@ +SIP Specification Files +======================= + +A SIP specification consists of some C/C++ type and function declarations and +some directives. The declarations may contain annotations which provide SIP +with additional information that cannot be expressed in C/C++. SIP does not +include a full C/C++ parser. + +It is important to understand that a SIP specification describes the Python +API, i.e. the API available to the Python programmer when they ``import`` the +generated module. It does not have to accurately represent the underlying +C/C++ library. There is nothing wrong with omitting functions that make +little sense in a Python context, or adding functions implemented with +handwritten code that have no C/C++ equivalent. It is even possible (and +sometimes necessary) to specify a different super-class hierarchy for a C++ +class. All that matters is that the generated code compiles properly. + +In most cases the Python API matches the C/C++ API. In some cases handwritten +code (see :directive:`%MethodCode`) is used to map from one to the other +without SIP having to know the details itself. However, there are a few cases +where SIP generates a thin wrapper around a C++ method or constructor (see +:ref:`ref-derived-classes`) and needs to know the exact C++ signature. To deal +with these cases SIP allows two signatures to be specified. For example:: + + class Klass + { + public: + // The Python signature is a tuple, but the underlying C++ signature + // is a 2 element array. + Klass(SIP_PYTUPLE) [(int *)]; + %MethodCode + int iarr[2]; + + if (PyArg_ParseTuple(a0, "ii", &iarr[0], &iarr[1])) + { + // Note that we use the SIP generated derived class + // constructor. + Py_BEGIN_ALLOW_THREADS + sipCpp = new sipKlass(iarr); + Py_END_ALLOW_THREADS + } + %End + }; + + +Syntax Definition +----------------- + +The following is a semi-formal description of the syntax of a specification +file. + +.. parsed-literal:: + + *specification* ::= {*module-statement*} + + *module-statement* ::= [*module-directive* | *statement*] + + *module-directive* ::= [ + :directive:`%API` | + :directive:`%CModule` | + :directive:`%CompositeModule` | + :directive:`%ConsolidatedModule` | + :directive:`%Copying` | + :directive:`%DefaultEncoding` | + :directive:`%DefaultMetatype` | + :directive:`%DefaultSupertype` | + :directive:`%Doc` | + :directive:`%ExportedDoc` | + :directive:`%ExportedHeaderCode` | + :directive:`%Feature` | + :directive:`%Import` | + :directive:`%Include` | + :directive:`%InitialisationCode` | + :directive:`%License` | + :directive:`%MappedType` | + :directive:`%Module` | + :directive:`%ModuleCode` | + :directive:`%ModuleHeaderCode` | + :directive:`%OptionalInclude` | + :directive:`%Platforms` | + :directive:`%PreInitialisationCode` | + :directive:`%PostInitialisationCode` | + :directive:`%Timeline` | + :directive:`%UnitCode` | + *mapped-type-template*] + + *statement* :: [*class-statement* | *function* | *variable*] + + *class-statement* :: [ + :directive:`%If` | + *class* | + *class-template* | + *enum* | + *namespace* | + *opaque-class* | + *operator* | + *struct* | + *typedef* | + *exception*] + + *class* ::= **class** *name* [**:** *super-classes*] [*class-annotations*] + **{** {*class-line*} **};** + + *super-classes* ::= *name* [**,** *super-classes*] + + *class-line* ::= [ + *class-statement* | + :directive:`%BIGetBufferCode` | + :directive:`%BIGetReadBufferCode` | + :directive:`%BIGetWriteBufferCode` | + :directive:`%BIGetSegCountCode` | + :directive:`%BIGetCharBufferCode` | + :directive:`%BIReleaseBufferCode` | + :directive:`%ConvertToSubClassCode` | + :directive:`%ConvertToTypeCode` | + :directive:`%Docstring` | + :directive:`%GCClearCode` | + :directive:`%GCTraverseCode` | + :directive:`%PickleCode` | + :directive:`%TypeCode` | + :directive:`%TypeHeaderCode` | + *constructor* | + *destructor* | + *method* | + *static-method* | + *virtual-method* | + *special-method* | + *operator* | + *virtual-operator* | + *class-variable* | + **public:** | + **public Q_SLOTS:** | + **public slots:** | + **protected:** | + **protected Q_SLOTS:** | + **protected slots:** | + **private:** | + **private Q_SLOTS:** | + **private slots:** | + **Q_SIGNALS:** | + **signals:**] + + *constructor* ::= [**explicit**] *name* **(** [*argument-list*] **)** + [*exceptions*] [*function-annotations*] + [*c++-constructor-signature*] **;** [:directive:`%Docstring`] + [:directive:`%MethodCode`] + + *c++-constructor-signature* ::= **[(** [*argument-list*] **)]** + + *destructor* ::= [**virtual**] **~** *name* **()** [*exceptions*] [**= 0**] + [*function-annotations*] **;** [:directive:`%MethodCode`] + [:directive:`%VirtualCatcherCode`] + + *method* ::= [**Q_SIGNAL**] [**Q_SLOT**] *type* *name* **(** + [*argument-list*] **)** [**const**] [*exceptions*] [**= 0**] + [*function-annotations*] [*c++-signature*] **;** + [:directive:`%Docstring`] [:directive:`%MethodCode`] + + *c++-signature* ::= **[** *type* **(** [*argument-list*] **)]** + + *static-method* ::= **static** *function* + + *virtual-method* ::= [**Q_SIGNAL**] [**Q_SLOT**] **virtual** *type* *name* + **(** [*argument-list*] **)** [**const**] [*exceptions*] [**= 0**] + [*function-annotations*] [*c++-signature*] **;** + [:directive:`%MethodCode`] [:directive:`%VirtualCatcherCode`] + + *special-method* ::= *type* *special-method-name* + **(** [*argument-list*] **)** [*function-annotations*] **;** + [:directive:`%MethodCode`] + + *special-method-name* ::= [**__abs__** | **__add__** | **__and__** | + **__bool__** | **__call__** | **__cmp__** | **__contains__** | + **__delitem__** | **__div__** | **__eq__** | **__float__** | + **__floordiv__** | **__ge__** | **__getitem__** | **__gt__** | + **__hash__** | **__iadd__** | **__iand__** | **__idiv__** | + **__ifloordiv__** | **__ilshift__** | **__imod__** | **__imul__** | + **__index__** | **__int__** | **__invert__** | **__ior__** | + **__irshift__** | **__isub__** | **__iter__** | **__itruediv__** | + **__ixor__** | **__le__** | **__len__** | **__long__** | + **__lshift__** | **__lt__** | **__mod__** | **__mul__** | + **__ne__** | **__neg__** | **__next__** | **__nonzero__** | + **__or__** | **__pos__** | **__repr__** | **__rshift__** | + **__setitem__** | **__str__** | **__sub__** | **__truediv__** | + **__xor__**] + + *operator* ::= *operator-type* + **(** [*argument-list*] **)** [**const**] [*exceptions*] + [*function-annotations*] **;** [:directive:`%MethodCode`] + + *virtual-operator* ::= **virtual** *operator-type* + **(** [*argument-list*] **)** [**const**] [*exceptions*] [**= 0**] + [*function-annotations*] **;** [:directive:`%MethodCode`] + [:directive:`%VirtualCatcherCode`] + + *operatator-type* ::= [ *operator-function* | *operator-cast* ] + + *operator-function* ::= *type* **operator** *operator-name* + + *operator-cast* ::= **operator** *type* + + *operator-name* ::= [**+** | **-** | ***** | **/** | **%** | **&** | + **|** | **^** | **<<** | **>>** | **+=** | **-=** | ***=** | + **/=** | **%=** | **&=** | **|=** | **^=** | **<<=** | **>>=** | + **~** | **()** | **[]** | **<** | **<=** | **==** | **!=** | + **>** | **>>=** | **=**] + + *class-variable* ::= [**static**] *variable* + + *class-template* :: = **template** **<** *type-list* **>** *class* + + *mapped-type-template* :: = **template** **<** *type-list* **>** + :directive:`%MappedType` + + *enum* ::= **enum** [*name*] [*enum-annotations*] **{** {*enum-line*} **};** + + *enum-line* ::= [:directive:`%If` | *name* [*enum-annotations*] **,** + + *function* ::= *type* *name* **(** [*argument-list*] **)** [*exceptions*] + [*function-annotations*] **;** [:directive:`%Docstring`] + [:directive:`%MethodCode`] + + *namespace* ::= **namespace** *name* **{** {*namespace-line*} **};** + + *namespace-line* ::= [:directive:`%TypeHeaderCode` | *statement*] + + *opaque-class* ::= **class** *scoped-name* **;** + + *struct* ::= **struct** *name* **{** {*class-line*} **};** + + *typedef* ::= **typedef** [*typed-name* | *function-pointer*] + *typedef-annotations* **;** + + *variable*::= *typed-name* [*variable-annotations*] **;** + [:directive:`%AccessCode`] [:directive:`%GetCode`] + [:directive:`%SetCode`] + + *exception* ::= :directive:`%Exception` *exception-name* [*exception-base*] + **{** [:directive:`%TypeHeaderCode`] :directive:`%RaiseCode` **};** + + *exception-name* ::= *scoped-name* + + *exception-base* ::= **(** [*exception-name* | *python-exception*] **)** + + *python-exception* ::= [**SIP_Exception** | **SIP_StopIteration** | + **SIP_StandardError** | **SIP_ArithmeticError** | + **SIP_LookupError** | **SIP_AssertionError** | + **SIP_AttributeError** | **SIP_EOFError** | + **SIP_FloatingPointError** | **SIP_EnvironmentError** | + **SIP_IOError** | **SIP_OSError** | **SIP_ImportError** | + **SIP_IndexError** | **SIP_KeyError** | **SIP_KeyboardInterrupt** | + **SIP_MemoryError** | **SIP_NameError** | **SIP_OverflowError** | + **SIP_RuntimeError** | **SIP_NotImplementedError** | + **SIP_SyntaxError** | **SIP_IndentationError** | **SIP_TabError** | + **SIP_ReferenceError** | **SIP_SystemError** | **SIP_SystemExit** | + **SIP_TypeError** | **SIP_UnboundLocalError** | + **SIP_UnicodeError** | **SIP_UnicodeEncodeError** | + **SIP_UnicodeDecodeError** | **SIP_UnicodeTranslateError** | + **SIP_ValueError** | **SIP_ZeroDivisionError** | + **SIP_WindowsError** | **SIP_VMSError**] + + *exceptions* ::= **throw (** [*exception-list*] **)** + + *exception-list* ::= *scoped-name* [**,** *exception-list*] + + *argument-list* ::= *argument* [**,** *argument-list*] [**,** **...**] + + *argument* ::= [ + *type* [*name*] [*argument-annotations*] [*default-value*] | + :stype:`SIP_ANYSLOT` [*default-value*] | + :stype:`SIP_QOBJECT` | + :stype:`SIP_RXOBJ_CON` | + :stype:`SIP_RXOBJ_DIS` | + :stype:`SIP_SIGNAL` [*default-value*] | + :stype:`SIP_SLOT` [*default-value*] | + :stype:`SIP_SLOT_CON` | + :stype:`SIP_SLOT_DIS`] + + *default-value* ::= **=** *expression* + + *expression* ::= [*value* | *value* *binary-operator* *expression*] + + *value* ::= [*unary-operator*] *simple-value* + + *simple-value* ::= [*scoped-name* | *function-call* | *real-value* | + *integer-value* | *boolean-value* | *string-value* | + *character-value*] + + *typed-name*::= *type* *name* + + *function-pointer*::= *type* **(*** *name* **)(** [*type-list*] **)** + + *type-list* ::= *type* [**,** *type-list*] + + *function-call* ::= *scoped-name* **(** [*value-list*] **)** + + *value-list* ::= *value* [**,** *value-list*] + + *real-value* ::= a floating point number + + *integer-value* ::= a number + + *boolean-value* ::= [**true** | **false**] + + *string-value* ::= **"** {*character*} **"** + + *character-value* ::= **'** *character* **'** + + *unary-operator* ::= [**!** | **~** | **-** | **+**] + + *binary-operator* ::= [**-** | **+** | ***** | **/** | **&** | **|**] + + *argument-annotations* ::= see :ref:`ref-arg-annos` + + *class-annotations* ::= see :ref:`ref-class-annos` + + *enum-annotations* ::= see :ref:`ref-enum-annos` + + *function-annotations* ::= see :ref:`ref-function-annos` + + *typedef-annotations* ::= see :ref:`ref-typedef-annos` + + *variable-annotations* ::= see :ref:`ref-variable-annos` + + *type* ::= [**const**] *base-type* {*****} [**&**] + + *type-list* ::= *type* [**,** *type-list*] + + *base-type* ::= [*scoped-name* | *template* | **struct** *scoped-name* | + **char** | **signed char** | **unsigned char** | **wchar_t** | + **int** | **unsigned** | **unsigned int** | + **short** | **unsigned short** | + **long** | **unsigned long** | + **long long** | **unsigned long long** | + **float** | **double** | + **bool** | + **void** | + :stype:`SIP_PYCALLABLE` | + :stype:`SIP_PYDICT` | + :stype:`SIP_PYLIST` | + :stype:`SIP_PYOBJECT` | + :stype:`SIP_PYSLICE` | + :stype:`SIP_PYTUPLE` | + :stype:`SIP_PYTYPE`] + + *scoped-name* ::= *name* [**::** *scoped-name*] + + *template* ::= *scoped-name* **<** *type-list* **>** + + *dotted-name* ::= *name* [**.** *dotted-name*] + + *name* ::= _A-Za-z {_A-Za-z0-9} + +Here is a short list of differences between C++ and the subset supported by +SIP that might trip you up. + + - SIP does not support the use of ``[]`` in types. Use pointers instead. + + - A global ``operator`` can only be defined if its first argument is a + class or a named enum that has been wrapped in the same module. + + - Variables declared outside of a class are effectively read-only. + + - A class's list of super-classes doesn't not include any access specifier + (e.g. ``public``). + + +Variable Numbers of Arguments +----------------------------- + +SIP supports the use of ``...`` as the last part of a function signature. Any +remaining arguments are collected as a Python tuple. + + +Additional SIP Types +-------------------- + +SIP supports a number of additional data types that can be used in Python +signatures. + + +.. sip-type:: SIP_ANYSLOT + +This is both a ``const char *`` and a ``PyObject *`` that is used as the type +of the member instead of ``const char *`` in functions that implement the +connection or disconnection of an explicitly generated signal to a slot. +Handwritten code must be provided to interpret the conversion correctly. + + +.. sip-type:: SIP_PYCALLABLE + +This is a ``PyObject *`` that is a Python callable object. + + +.. sip-type:: SIP_PYDICT + +This is a ``PyObject *`` that is a Python dictionary object. + + +.. sip-type:: SIP_PYLIST + +This is a ``PyObject *`` that is a Python list object. + + +.. sip-type:: SIP_PYOBJECT + +This is a ``PyObject *`` of any Python type. + + +.. sip-type:: SIP_PYSLICE + +This is a ``PyObject *`` that is a Python slice object. + + +.. sip-type:: SIP_PYTUPLE + +This is a ``PyObject *`` that is a Python tuple object. + + +.. sip-type:: SIP_PYTYPE + +This is a ``PyObject *`` that is a Python type object. + + +.. sip-type:: SIP_QOBJECT + +This is a ``QObject *`` that is a C++ instance of a class derived from Qt's +``QObject`` class. + + +.. sip-type:: SIP_RXOBJ_CON + +This is a ``QObject *`` that is a C++ instance of a class derived from Qt's +``QObject`` class. It is used as the type of the receiver instead of ``const +QObject *`` in functions that implement a connection to a slot. + + +.. sip-type:: SIP_RXOBJ_DIS + +This is a ``QObject *`` that is a C++ instance of a class derived from Qt's +``QObject`` class. It is used as the type of the receiver instead of ``const +QObject *`` in functions that implement a disconnection from a slot. + + +.. sip-type:: SIP_SIGNAL + +This is a ``const char *`` that is used as the type of the signal instead of +``const char *`` in functions that implement the connection or disconnection +of an explicitly generated signal to a slot. + + +.. sip-type:: SIP_SLOT + +This is a ``const char *`` that is used as the type of the member instead of +``const char *`` in functions that implement the connection or disconnection +of an explicitly generated signal to a slot. + + +.. sip-type:: SIP_SLOT_CON + +This is a ``const char *`` that is used as the type of the member instead of +``const char *`` in functions that implement the connection of an internally +generated signal to a slot. The type includes a comma separated list of types +that is the C++ signature of of the signal. + +To take an example, ``QAccel::connectItem()`` connects an internally generated +signal to a slot. The signal is emitted when the keyboard accelerator is +activated and it has a single integer argument that is the ID of the +accelerator. The C++ signature is:: + + bool connectItem(int id, const QObject *receiver, const char *member); + +The corresponding SIP specification is:: + + bool connectItem(int, SIP_RXOBJ_CON, SIP_SLOT_CON(int)); + + +.. sip-type:: SIP_SLOT_DIS + +This is a ``const char *`` that is used as the type of the member instead of +``const char *`` in functions that implement the disconnection of an +internally generated signal to a slot. The type includes a comma separated +list of types that is the C++ signature of of the signal. + + +Classic Division and True Division +---------------------------------- + +SIP supports the ``__div__`` and ``__truediv__`` special methods (and the +corresponding inplace versions) for both Python v2 and v3. + +For Python v2 the ``__div__`` method will be used for both classic and true +division if a ``__truediv__`` method is not defined. + +For Python v3 the ``__div__`` method will be used for true division if a +``__truediv__`` method is not defined. + +For all versions of Python, if both methods are defined then ``__div__`` +should be defined first. diff --git a/sphinx/using.rst b/sphinx/using.rst new file mode 100644 index 0000000..ff121ce --- /dev/null +++ b/sphinx/using.rst @@ -0,0 +1,662 @@ +.. _ref-using: + +Using SIP +========= + +Bindings are generated by the SIP code generator from a number of specification +files, typically with a ``.sip`` extension. Specification files look very +similar to C and C++ header files, but often with additional information (in +the form of a *directive* or an *annotation*) and code so that the bindings +generated can be finely tuned. + + +.. _ref-simple-c++-example: + +A Simple C++ Example +-------------------- + +We start with a simple example. Let's say you have a (fictional) C++ library +that implements a single class called ``Word``. The class has one constructor +that takes a ``\0`` terminated character string as its single argument. The +class has one method called ``reverse()`` which takes no arguments and returns +a ``\0`` terminated character string. The interface to the class is defined in +a header file called ``word.h`` which might look something like this:: + + // Define the interface to the word library. + + class Word { + const char *the_word; + + public: + Word(const char *w); + + char *reverse() const; + }; + +The corresponding SIP specification file would then look something like this:: + + // Define the SIP wrapper to the word library. + + %Module word 0 + + class Word { + + %TypeHeaderCode + #include <word.h> + %End + + public: + Word(const char *w); + + char *reverse() const; + }; + +Obviously a SIP specification file looks very much like a C++ (or C) header +file, but SIP does not include a full C++ parser. Let's look at the +differences between the two files. + + - The :directive:`%Module` directive has been added [#]_. This is used to + name the Python module that is being created and to give it a + *generation* number. In this example these are ``word`` and ``0`` + respectively. The generation number is effectively the version number of + the module. + + - The :directive:`%TypeHeaderCode` directive has been added. The text + between this and the following :directive:`%End` directive is included + literally in the code that SIP generates. Normally it is used, as in + this case, to ``#include`` the corresponding C++ (or C) header file [#]_. + + - The declaration of the private variable ``this_word`` has been removed. + SIP does not support access to either private or protected instance + variables. + +If we want to we can now generate the C++ code in the current directory by +running the following command:: + + sip -c . word.sip + +However, that still leaves us with the task of compiling the generated code and +linking it against all the necessary libraries. It's much easier to use the +:ref:`SIP build system <ref-build-system>` to do the whole thing. + +Using the SIP build system is simply a matter of writing a small Python script. +In this simple example we will assume that the ``word`` library we are wrapping +and it's header file are installed in standard system locations and will be +found by the compiler and linker without having to specify any additional +flags. In a more realistic example your Python script may take command line +options, or search a set of directories to deal with different configurations +and installations. + +This is the simplest script (conventionally called ``configure.py``):: + + import os + import sipconfig + + # The name of the SIP build file generated by SIP and used by the build + # system. + build_file = "word.sbf" + + # Get the SIP configuration information. + config = sipconfig.Configuration() + + # Run SIP to generate the code. + os.system(" ".join([config.sip_bin, "-c", ".", "-b", build_file, "word.sip"])) + + # Create the Makefile. + makefile = sipconfig.SIPModuleMakefile(config, build_file) + + # Add the library we are wrapping. The name doesn't include any platform + # specific prefixes or extensions (e.g. the "lib" prefix on UNIX, or the + # ".dll" extension on Windows). + makefile.extra_libs = ["word"] + + # Generate the Makefile itself. + makefile.generate() + +Hopefully this script is self-documenting. The key parts are the +``Configuration`` and ``SIPModuleMakefile`` classes. The build system contains +other Makefile classes, for example to build programs or to call other +Makefiles in sub-directories. + +After running the script (using the Python interpreter the extension module is +being created for) the generated C++ code and ``Makefile`` will be in the +current directory. + +To compile and install the extension module, just run the following +commands [#]_:: + + make + make install + +That's all there is to it. + +See :ref:`ref-distutils` for an example of how to build this example using +distutils. + +.. [#] All SIP directives start with a ``%`` as the first non-whitespace + character of a line. +.. [#] SIP includes many code directives like this. They differ in where the + supplied code is placed by SIP in the generated code. +.. [#] On Windows you might run ``nmake`` or ``mingw32-make`` instead. + + +A Simple C Example +------------------ + +Let's now look at a very similar example of wrapping a fictional C library:: + + /* Define the interface to the word library. */ + + struct Word { + const char *the_word; + }; + + struct Word *create_word(const char *w); + char *reverse(struct Word *word); + +The corresponding SIP specification file would then look something like this:: + + /* Define the SIP wrapper to the word library. */ + + %CModule word 0 + + struct Word { + + %TypeHeaderCode + #include <word.h> + %End + + const char *the_word; + }; + + struct Word *create_word(const char *w) /Factory/; + char *reverse(struct Word *word); + +Again, let's look at the differences between the two files. + + - The :directive:`%CModule` directive has been added. This has the same + syntax as the :directive:`%Module` directive used in the previous example + but tells SIP that the library being wrapped is implemented in C rather + than C++. + + - The :directive:`%TypeHeaderCode` directive has been added. + + - The :fanno:`Factory` annotation has been added to the ``create_word()`` + function. This tells SIP that a newly created structure is being + returned and it is owned by Python. + +The ``configure.py`` build system script described in the previous example can +be used for this example without change. + + +A More Complex C++ Example +-------------------------- + +In this last example we will wrap a fictional C++ library that contains a class +that is derived from a Qt class. This will demonstrate how SIP allows a class +hierarchy to be split across multiple Python extension modules, and will +introduce SIP's versioning system. + +The library contains a single C++ class called ``Hello`` which is derived from +Qt's ``QLabel`` class. It behaves just like ``QLabel`` except that the text +in the label is hard coded to be ``Hello World``. To make the example more +interesting we'll also say that the library only supports Qt v4.2 and later, +and also includes a function called ``setDefault()`` that is not implemented +in the Windows version of the library. + +The ``hello.h`` header file looks something like this:: + + // Define the interface to the hello library. + + #include <qlabel.h> + #include <qwidget.h> + #include <qstring.h> + + class Hello : public QLabel { + // This is needed by the Qt Meta-Object Compiler. + Q_OBJECT + + public: + Hello(QWidget *parent = 0); + + private: + // Prevent instances from being copied. + Hello(const Hello &); + Hello &operator=(const Hello &); + }; + + #if !defined(Q_OS_WIN) + void setDefault(const QString &def); + #endif + +The corresponding SIP specification file would then look something like this:: + + // Define the SIP wrapper to the hello library. + + %Module hello 0 + + %Import QtGui/QtGuimod.sip + + %If (Qt_4_2_0 -) + + class Hello : QLabel { + + %TypeHeaderCode + #include <hello.h> + %End + + public: + Hello(QWidget *parent /TransferThis/ = 0); + + private: + Hello(const Hello &); + }; + + %If (!WS_WIN) + void setDefault(const QString &def); + %End + + %End + +Again we look at the differences, but we'll skip those that we've looked at in +previous examples. + + - The :directive:`%Import` directive has been added to specify that we are + extending the class hierarchy defined in the file ``QtGui/QtGuimod.sip``. + This file is part of PyQt. The build system will take care of finding + the file's exact location. + + - The :directive:`%If` directive has been added to specify that everything + [#]_ up to the matching :directive:`%End` directive only applies to Qt + v4.2 and later. ``Qt_4_2_0`` is a *tag* defined in ``QtCoremod.sip`` + [#]_ using the :directive:`%Timeline` directive. :directive:`%Timeline` + is used to define a tag for each version of a library's API you are + wrapping allowing you to maintain all the different versions in a single + SIP specification. The build system provides support to ``configure.py`` + scripts for working out the correct tags to use according to which + version of the library is actually installed. + + - The ``public`` keyword used in defining the super-classes has been + removed. This is not supported by SIP. + + - The :aanno:`TransferThis` annotation has been added to the constructor's + argument. It specifies that if the argument is not 0 (i.e. the ``Hello`` + instance being constructed has a parent) then ownership of the instance + is transferred from Python to C++. It is needed because Qt maintains + objects (i.e. instances derived from the ``QObject`` class) in a + hierachy. When an object is destroyed all of its children are also + automatically destroyed. It is important, therefore, that the Python + garbage collector doesn't also try and destroy them. This is covered in + more detail in :ref:`ref-object-ownership`. SIP provides many other + annotations that can be applied to arguments, functions and classes. + Multiple annotations are separated by commas. Annotations may have + values. + + - The ``=`` operator has been removed. This operator is not supported by + SIP. + + - The :directive:`%If` directive has been added to specify that everything + up to the matching :directive:`%End` directive does not apply to Windows. + ``WS_WIN`` is another tag defined by PyQt, this time using the + :directive:`%Platforms` directive. Tags defined by the + :directive:`%Platforms` directive are mutually exclusive, i.e. only one + may be valid at a time [#]_. + +One question you might have at this point is why bother to define the private +copy constructor when it can never be called from Python? The answer is to +prevent the automatic generation of a public copy constructor. + +We now look at the ``configure.py`` script. This is a little different to the +script in the previous examples for two related reasons. + +Firstly, PyQt includes a pure Python module called ``pyqtconfig`` that extends +the SIP build system for modules, like our example, that build on top of PyQt. +It deals with the details of which version of Qt is being used (i.e. it +determines what the correct tags are) and where it is installed. This is +called a module's configuration module. + +Secondly, we generate a configuration module (called ``helloconfig``) for our +own ``hello`` module. There is no need to do this, but if there is a chance +that somebody else might want to extend your C++ library then it would make +life easier for them. + +Now we have two scripts. First the ``configure.py`` script:: + + import os + import sipconfig + from PyQt4 import pyqtconfig + + # The name of the SIP build file generated by SIP and used by the build + # system. + build_file = "hello.sbf" + + # Get the PyQt configuration information. + config = pyqtconfig.Configuration() + + # Get the extra SIP flags needed by the imported PyQt modules. Note that + # this normally only includes those flags (-x and -t) that relate to SIP's + # versioning system. + pyqt_sip_flags = config.pyqt_sip_flags + + # Run SIP to generate the code. Note that we tell SIP where to find the qt + # module's specification files using the -I flag. + os.system(" ".join([config.sip_bin, "-c", ".", "-b", build_file, "-I", config.pyqt_sip_dir, pyqt_sip_flags, "hello.sip"])) + + # We are going to install the SIP specification file for this module and + # its configuration module. + installs = [] + + installs.append(["hello.sip", os.path.join(config.default_sip_dir, "hello")]) + + installs.append(["helloconfig.py", config.default_mod_dir]) + + # Create the Makefile. The QtGuiModuleMakefile class provided by the + # pyqtconfig module takes care of all the extra preprocessor, compiler and + # linker flags needed by the Qt library. + makefile = pyqtconfig.QtGuiModuleMakefile( + configuration=config, + build_file=build_file, + installs=installs + ) + + # Add the library we are wrapping. The name doesn't include any platform + # specific prefixes or extensions (e.g. the "lib" prefix on UNIX, or the + # ".dll" extension on Windows). + makefile.extra_libs = ["hello"] + + # Generate the Makefile itself. + makefile.generate() + + # Now we create the configuration module. This is done by merging a Python + # dictionary (whose values are normally determined dynamically) with a + # (static) template. + content = { + # Publish where the SIP specifications for this module will be + # installed. + "hello_sip_dir": config.default_sip_dir, + + # Publish the set of SIP flags needed by this module. As these are the + # same flags needed by the qt module we could leave it out, but this + # allows us to change the flags at a later date without breaking + # scripts that import the configuration module. + "hello_sip_flags": pyqt_sip_flags + } + + # This creates the helloconfig.py module from the helloconfig.py.in + # template and the dictionary. + sipconfig.create_config_module("helloconfig.py", "helloconfig.py.in", content) + +Next we have the ``helloconfig.py.in`` template script:: + + from PyQt4 import pyqtconfig + + # These are installation specific values created when Hello was configured. + # The following line will be replaced when this template is used to create + # the final configuration module. + # @SIP_CONFIGURATION@ + + class Configuration(pyqtconfig.Configuration): + """The class that represents Hello configuration values. + """ + def __init__(self, sub_cfg=None): + """Initialise an instance of the class. + + sub_cfg is the list of sub-class configurations. It should be None + when called normally. + """ + # This is all standard code to be copied verbatim except for the + # name of the module containing the super-class. + if sub_cfg: + cfg = sub_cfg + else: + cfg = [] + + cfg.append(_pkg_config) + + pyqtconfig.Configuration.__init__(self, cfg) + + class HelloModuleMakefile(pyqtconfig.QtGuiModuleMakefile): + """The Makefile class for modules that %Import hello. + """ + def finalise(self): + """Finalise the macros. + """ + # Make sure our C++ library is linked. + self.extra_libs.append("hello") + + # Let the super-class do what it needs to. + pyqtconfig.QtGuiModuleMakefile.finalise(self) + +Again, we hope that the scripts are self documenting. + +.. [#] Some parts of a SIP specification aren't subject to version control. +.. [#] Actually in ``versions.sip``. PyQt uses the :directive:`%Include` + directive to split the SIP specification for Qt across a large number of + separate ``.sip`` files. +.. [#] Tags can also be defined by the :directive:`%Feature` directive. These + tags are not mutually exclusive, i.e. any number may be valid at a time. + + +.. _ref-object-ownership: + +Ownership of Objects +-------------------- + +When a C++ instance is wrapped a corresponding Python object is created. The +Python object behaves as you would expect in regard to garbage collection - it +is garbage collected when its reference count reaches zero. What then happens +to the corresponding C++ instance? The obvious answer might be that the +instance's destructor is called. However the library API may say that when the +instance is passed to a particular function, the library takes ownership of the +instance, i.e. responsibility for calling the instance's destructor is +transferred from the SIP generated module to the library. + +Ownership of an instance may also be associated with another instance. The +implication being that the owned instance will automatically be destroyed if +the owning instance is destroyed. SIP keeps track of these relationships to +ensure that Python's cyclic garbage collector can detect and break any +reference cycles between the owning and owned instances. The association is +implemented as the owning instance taking a reference to the owned instance. + +The TransferThis, Transfer and TransferBack annotations are used to specify +where, and it what direction, transfers of ownership happen. It is very +important that these are specified correctly to avoid crashes (where both +Python and C++ call the destructor) and memory leaks (where neither Python and +C++ call the destructor). + +This applies equally to C structures where the structure is returned to the +heap using the ``free()`` function. + +See also :cfunc:`sipTransferTo()`, :cfunc:`sipTransferBack()` and +:cfunc:`sipTransferBreak()`. + + +.. _ref-types-metatypes: + +Types and Meta-types +-------------------- + +Every Python object (with the exception of the :class:`object` object itself) +has a meta-type and at least one super-type. By default an object's meta-type +is the meta-type of its first super-type. + +SIP implements two super-types, :class:`sip.simplewrapper` and +:class:`sip.wrapper`, and a meta-type, :class:`sip.wrappertype`. + +:class:`sip.simplewrapper` is the super-type of :class:`sip.wrapper`. The +super-type of :class:`sip.simplewrapper` is :class:`object`. + +:class:`sip.wrappertype` is the meta-type of both :class:`sip.simplewrapper` +and :class:`sip.wrapper`. The super-type of :class:`sip.wrappertype` is +:class:`type`. + +:class:`sip.wrapper` supports the concept of object ownership described in +:ref:`ref-object-ownership` and, by default, is the super-type of all the types +that SIP generates. + +:class:`sip.simplewrapper` does not support the concept of object ownership but +SIP generated types that are sub-classed from it have Python objects that take +less memory. + +SIP allows a class's meta-type and super-type to be explicitly specified using +the :canno:`Metatype` and :canno:`Supertype` class annotations. + +SIP also allows the default meta-type and super-type to be changed for a module +using the :directive:`%DefaultMetatype` and :directive:`%DefaultSupertype` +directives. Unlike the default super-type, the default meta-type is inherited +by importing modules. + +If you want to use your own meta-type or super-type then they must be +sub-classed from one of the SIP provided types. Your types must be registered +using :cfunc:`sipRegisterPyType()`. This is normally done in code specified +using the :directive:`%InitialisationCode` directive. + +As an example, PyQt4 uses :directive:`%DefaultMetatype` to specify a new +meta-type that handles the interaction with Qt's own meta-type system. It also +uses :directive:`%DefaultSupertype` to specify that the smaller +:class:`sip.simplewrapper` super-type is normally used. Finally it uses +:canno:`Supertype` as an annotation of the ``QObject`` class to override the +default and use :class:`sip.wrapper` as the super-type so that the parent/child +relationships of ``QObject`` instances are properly maintained. + + +.. _ref-lazy-type-attributes: + +Lazy Type Attributes +-------------------- + +Instead of populating a wrapped type's dictionary with its attributes (or +descriptors for those attributes) SIP only creates objects for those attributes +when they are actually needed. This is done to reduce the memory footprint and +start up time when used to wrap large libraries with hundreds of classes and +tens of thousands of attributes. + +SIP allows you to extend the handling of lazy attributes to your own attribute +types by allowing you to register an attribute getter handler (using +:cfunc:`sipRegisterAttributeGetter()`). This will be called just before a +type's dictionary is accessed for the first time. + + +Support for Python's Buffer Interface +------------------------------------- + +SIP supports Python's buffer interface in that whenever C/C++ requires a +``char`` or ``char *`` type then any Python type that supports the buffer +interface (including ordinary Python strings) can be used. + +If a buffer is made up of a number of segments then all but the first will be +ignored. + + +Support for Wide Characters +--------------------------- + +SIP v4.6 introduced support for wide characters (i.e. the ``wchar_t`` type). +Python's C API includes support for converting between unicode objects and wide +character strings and arrays. When converting from a unicode object to wide +characters SIP creates the string or array on the heap (using memory allocated +using :cfunc:`sipMalloc()`). This then raises the problem of how this memory +is subsequently freed. + +The following describes how SIP handles this memory in the different situations +where this is an issue. + + - When a wide string or array is passed to a function or method then the + memory is freed (using :cfunc:`sipFree()`) after than function or method + returns. + + - When a wide string or array is returned from a virtual method then SIP + does not free the memory until the next time the method is called. + + - When an assignment is made to a wide string or array instance variable + then SIP does not first free the instance's current string or array. + + +.. _ref-gil: + +The Python Global Interpreter Lock +---------------------------------- + +Python's Global Interpretor Lock (GIL) must be acquired before calls can be +made to the Python API. It should also be released when a potentially +blocking call to C/C++ library is made in order to allow other Python threads +to be executed. In addition, some C/C++ libraries may implement their own +locking strategies that conflict with the GIL causing application deadlocks. +SIP provides ways of specifying when the GIL is released and acquired to +ensure that locking problems can be avoided. + +SIP always ensures that the GIL is acquired before making calls to the Python +API. By default SIP does not release the GIL when making calls to the C/C++ +library being wrapped. The :fanno:`ReleaseGIL` annotation can be used to +override this behaviour when required. + +If SIP is given the :option:`-g <sip -g>` command line option then the default +behaviour is changed and SIP releases the GIL every time is makes calls to the +C/C++ library being wrapped. The :fanno:`HoldGIL` annotation can be used to +override this behaviour when required. + + +.. _ref-incompat-apis: + +Managing Incompatible APIs +-------------------------- + +.. versionadded:: 4.9 + +Sometimes it is necessary to change the way something is wrapped in a way that +introduces an incompatibility. For example a new feature of Python may +suggest that something may be wrapped in a different way to exploit that +feature. + +SIP's :directive:`%Feature` directive could be used to provide two different +implementations. However this would mean that the choice between the two +implementations would have to be made when building the generated module +potentially causing all sorts of deployment problems. It may also require +applications to work out which implementation was available and to change +their behaviour accordingly. + +Instead SIP provides limited support for providing multiple implementations +(of classes, mapped types and functions) that can be selected by an +application at run-time. It is then up to the application developer how they +want to manage the migration from the old API to the new, incompatible API. + +This support is implemented in three parts. + +Firstly the :directive:`%API` directive is used to define the name of an API +and its default version number. The default version number is the one used if +an application doesn't explicitly set the version number to use. + +Secondly the :canno:`API class <API>`, :manno:`mapped type <API>` or +:fanno:`function <API>` annotation is applied accordingly to specify the API +and range of version numbers that a particular class, mapped type or function +implementation should be enabled for. + +Finally the application calls :func:`sip.setapi` to specify the version number +of the API that should be enabled. This call must be made before any module +that has multiple implementations is imported for the first time. + +Note this mechanism is not intended as a way or providing equally valid +alternative APIs. For example:: + + %API MyAPI 1 + + class Foo + { + public: + void bar(); + }; + + class Baz : Foo + { + public: + void bar() /API=MyAPI:2-/; + }; + +If the following Python code is executed then an exception will be raised:: + + b = Baz() + b.bar() + +This is because when version 1 of the *MyAPI* API (the default) is enabled +there is no *Baz.bar()* implementation and *Foo.bar()* will not be called +instead as might be expected. |