sip for python

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``. Revised Directive Syntax ------------------------ .. versionadded:: 4.12 The directive syntax used in older versions has some problems: - it is inconsistent in places - it can be problematic to parse - it is inflexible. SIP v4.12 introduced a revised directive syntax that addresses these problems and deprecates the old syntax. Support for the old syntax will be removed in SIP v5. The revised syntax is: .. parsed-literal:: %Directive(arg = value, ...) { %Sub-directive ... }; A directive may have a number of arguments enclosed in parentheses followed by a number of sub-directives enclosed in braces. Individual arguments and sub-directives may be optional. Arguments may be specified in any order. If no arguments are specified then the parentheses can be omitted. If a directive has only one compulsory argument then its value may be specified after the directive name and instead of the parentheses. Sub-directives may be specified in any order. If no sub-directives are specified then the braces can be omitted. If a directive is used to specify handwritten code then it may not have sub-directives. In this case the syntax is: .. parsed-literal:: %Directive(arg = value, ...) *code* %End Ordinary C/C++ statements may also have sub-directives. These will also be enclosed in braces. The documentation for each directive describes the revised syntax. The older syntax should be used if compatibility with versions of SIP prior to v4.12 is required. List of Directives ------------------ .. directive:: %AccessCode .. parsed-literal:: %AccessCode *code* %End This sub-directive is used in 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 }; .. seealso:: :directive:`%GetCode`, :directive:`%SetCode` .. directive:: %API .. versionadded:: 4.9 .. parsed-literal:: %API(name = *name*, version = *integer*) 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(name=PyQt4, version=1) .. directive:: %AutoPyName .. versionadded:: 4.12 .. parsed-literal:: %AutoPyName(remove_leading = *string*) This is a sub-directive of the :directive:`%Module` directive used to specify a rule for automatically providing Python names for classes, enums, functions, methods, variables and exceptions. The directive may be specified any number of times and each rule will be applied in turn. Rules will not be applied if an item has been given an explicit Python name. ``remove_leading`` is a string that will be removed from the beginning of any C++ or C name. For example:: %Module PyQt4.QtCore { %AutoPyName(remove_leading="Q") } .. 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. :c:macro:`SIP_SSIZE_T` sipRes The handwritten code should set this to the length of the character buffer or -1 if there was an error. :c:macro:`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. :c:macro:`SIP_SSIZE_T` sipRes The handwritten code should set this to the length of the read buffer or -1 if there was an error. :c:macro:`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. :c:macro:`SIP_SSIZE_T` \*sipLenPtr This is the pointer used to return the total length in bytes of all segments of the buffer. :c:macro:`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`,