diff options
Diffstat (limited to 'doc/html')
44 files changed, 24570 insertions, 0 deletions
diff --git a/doc/html/_sources/annotations.txt b/doc/html/_sources/annotations.txt new file mode 100644 index 0000000..05ab847 --- /dev/null +++ b/doc/html/_sources/annotations.txt @@ -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/doc/html/_sources/build_system.txt b/doc/html/_sources/build_system.txt new file mode 100644 index 0000000..292836a --- /dev/null +++ b/doc/html/_sources/build_system.txt @@ -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/doc/html/_sources/builtin.txt b/doc/html/_sources/builtin.txt new file mode 100644 index 0000000..58c7019 --- /dev/null +++ b/doc/html/_sources/builtin.txt @@ -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/doc/html/_sources/c_api.txt b/doc/html/_sources/c_api.txt new file mode 100644 index 0000000..782056c --- /dev/null +++ b/doc/html/_sources/c_api.txt @@ -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/doc/html/_sources/command_line.txt b/doc/html/_sources/command_line.txt new file mode 100644 index 0000000..9c50cf4 --- /dev/null +++ b/doc/html/_sources/command_line.txt @@ -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/doc/html/_sources/directives.txt b/doc/html/_sources/directives.txt new file mode 100644 index 0000000..7e3a2e0 --- /dev/null +++ b/doc/html/_sources/directives.txt @@ -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/doc/html/_sources/distutils.txt b/doc/html/_sources/distutils.txt new file mode 100644 index 0000000..21a6b36 --- /dev/null +++ b/doc/html/_sources/distutils.txt @@ -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/doc/html/_sources/embedding.txt b/doc/html/_sources/embedding.txt new file mode 100644 index 0000000..114e3e8 --- /dev/null +++ b/doc/html/_sources/embedding.txt @@ -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/doc/html/_sources/incompatibilities.txt b/doc/html/_sources/incompatibilities.txt new file mode 100644 index 0000000..a006e4f --- /dev/null +++ b/doc/html/_sources/incompatibilities.txt @@ -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/doc/html/_sources/index.txt b/doc/html/_sources/index.txt new file mode 100644 index 0000000..ac9289c --- /dev/null +++ b/doc/html/_sources/index.txt @@ -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/doc/html/_sources/installation.txt b/doc/html/_sources/installation.txt new file mode 100644 index 0000000..3f9f823 --- /dev/null +++ b/doc/html/_sources/installation.txt @@ -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/doc/html/_sources/introduction.txt b/doc/html/_sources/introduction.txt new file mode 100644 index 0000000..8515243 --- /dev/null +++ b/doc/html/_sources/introduction.txt @@ -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/doc/html/_sources/python_api.txt b/doc/html/_sources/python_api.txt new file mode 100644 index 0000000..fa90411 --- /dev/null +++ b/doc/html/_sources/python_api.txt @@ -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/doc/html/_sources/specification_files.txt b/doc/html/_sources/specification_files.txt new file mode 100644 index 0000000..6ba3aba --- /dev/null +++ b/doc/html/_sources/specification_files.txt @@ -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/doc/html/_sources/using.txt b/doc/html/_sources/using.txt new file mode 100644 index 0000000..ff121ce --- /dev/null +++ b/doc/html/_sources/using.txt @@ -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. diff --git a/doc/html/_static/basic.css b/doc/html/_static/basic.css new file mode 100644 index 0000000..a04d654 --- /dev/null +++ b/doc/html/_static/basic.css @@ -0,0 +1,417 @@ +/** + * Sphinx stylesheet -- basic theme + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + */ + +/* -- main layout ----------------------------------------------------------- */ + +div.clearer { + clear: both; +} + +/* -- relbar ---------------------------------------------------------------- */ + +div.related { + width: 100%; + font-size: 90%; +} + +div.related h3 { + display: none; +} + +div.related ul { + margin: 0; + padding: 0 0 0 10px; + list-style: none; +} + +div.related li { + display: inline; +} + +div.related li.right { + float: right; + margin-right: 5px; +} + +/* -- sidebar --------------------------------------------------------------- */ + +div.sphinxsidebarwrapper { + padding: 10px 5px 0 10px; +} + +div.sphinxsidebar { + float: left; + width: 230px; + margin-left: -100%; + font-size: 90%; +} + +div.sphinxsidebar ul { + list-style: none; +} + +div.sphinxsidebar ul ul, +div.sphinxsidebar ul.want-points { + margin-left: 20px; + list-style: square; +} + +div.sphinxsidebar ul ul { + margin-top: 0; + margin-bottom: 0; +} + +div.sphinxsidebar form { + margin-top: 10px; +} + +div.sphinxsidebar input { + border: 1px solid #98dbcc; + font-family: sans-serif; + font-size: 1em; +} + +img { + border: 0; +} + +/* -- search page ----------------------------------------------------------- */ + +ul.search { + margin: 10px 0 0 20px; + padding: 0; +} + +ul.search li { + padding: 5px 0 5px 20px; + background-image: url(file.png); + background-repeat: no-repeat; + background-position: 0 7px; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li div.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} + +/* -- index page ------------------------------------------------------------ */ + +table.contentstable { + width: 90%; +} + +table.contentstable p.biglink { + line-height: 150%; +} + +a.biglink { + font-size: 1.3em; +} + +span.linkdescr { + font-style: italic; + padding-top: 5px; + font-size: 90%; +} + +/* -- general index --------------------------------------------------------- */ + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable dl, table.indextable dd { + margin-top: 0; + margin-bottom: 0; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +/* -- general body styles --------------------------------------------------- */ + +a.headerlink { + visibility: hidden; +} + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink { + visibility: visible; +} + +div.body p.caption { + text-align: inherit; +} + +div.body td { + text-align: left; +} + +.field-list ul { + padding-left: 1em; +} + +.first { + margin-top: 0 !important; +} + +p.rubric { + margin-top: 30px; + font-weight: bold; +} + +/* -- sidebars -------------------------------------------------------------- */ + +div.sidebar { + margin: 0 0 0.5em 1em; + border: 1px solid #ddb; + padding: 7px 7px 0 7px; + background-color: #ffe; + width: 40%; + float: right; +} + +p.sidebar-title { + font-weight: bold; +} + +/* -- topics ---------------------------------------------------------------- */ + +div.topic { + border: 1px solid #ccc; + padding: 7px 7px 0 7px; + margin: 10px 0 10px 0; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; + margin-top: 10px; +} + +/* -- admonitions ----------------------------------------------------------- */ + +div.admonition { + margin-top: 10px; + margin-bottom: 10px; + padding: 7px; +} + +div.admonition dt { + font-weight: bold; +} + +div.admonition dl { + margin-bottom: 0; +} + +p.admonition-title { + margin: 0px 10px 5px 0px; + font-weight: bold; +} + +div.body p.centered { + text-align: center; + margin-top: 25px; +} + +/* -- tables ---------------------------------------------------------------- */ + +table.docutils { + border: 0; + border-collapse: collapse; +} + +table.docutils td, table.docutils th { + padding: 1px 8px 1px 0; + border-top: 0; + border-left: 0; + border-right: 0; + border-bottom: 1px solid #aaa; +} + +table.field-list td, table.field-list th { + border: 0 !important; +} + +table.footnote td, table.footnote th { + border: 0 !important; +} + +th { + text-align: left; + padding-right: 5px; +} + +/* -- other body styles ----------------------------------------------------- */ + +dl { + margin-bottom: 15px; +} + +dd p { + margin-top: 0px; +} + +dd ul, dd table { + margin-bottom: 10px; +} + +dd { + margin-top: 3px; + margin-bottom: 10px; + margin-left: 30px; +} + +dt:target, .highlight { + background-color: #fbe54e; +} + +dl.glossary dt { + font-weight: bold; + font-size: 1.1em; +} + +.field-list ul { + margin: 0; + padding-left: 1em; +} + +.field-list p { + margin: 0; +} + +.refcount { + color: #060; +} + +.optional { + font-size: 1.3em; +} + +.versionmodified { + font-style: italic; +} + +.system-message { + background-color: #fda; + padding: 5px; + border: 3px solid red; +} + +.footnote:target { + background-color: #ffa +} + +.line-block { + display: block; + margin-top: 1em; + margin-bottom: 1em; +} + +.line-block .line-block { + margin-top: 0; + margin-bottom: 0; + margin-left: 1.5em; +} + +/* -- code displays --------------------------------------------------------- */ + +pre { + overflow: auto; +} + +td.linenos pre { + padding: 5px 0px; + border: 0; + background-color: transparent; + color: #aaa; +} + +table.highlighttable { + margin-left: 0.5em; +} + +table.highlighttable td { + padding: 0 0.5em 0 0.5em; +} + +tt.descname { + background-color: transparent; + font-weight: bold; + font-size: 1.2em; +} + +tt.descclassname { + background-color: transparent; +} + +tt.xref, a tt { + background-color: transparent; + font-weight: bold; +} + +h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { + background-color: transparent; +} + +/* -- math display ---------------------------------------------------------- */ + +img.math { + vertical-align: middle; +} + +div.body div.math p { + text-align: center; +} + +span.eqno { + float: right; +} + +/* -- printout stylesheet --------------------------------------------------- */ + +@media print { + div.document, + div.documentwrapper, + div.bodywrapper { + margin: 0 !important; + width: 100%; + } + + div.sphinxsidebar, + div.related, + div.footer, + #top-link { + display: none; + } +} diff --git a/doc/html/_static/default.css b/doc/html/_static/default.css new file mode 100644 index 0000000..42ed6ec --- /dev/null +++ b/doc/html/_static/default.css @@ -0,0 +1,218 @@ +/** + * Sphinx stylesheet -- default theme + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + */ + +@import url("basic.css"); + +/* -- page layout ----------------------------------------------------------- */ + +body { + font-family: sans-serif; + font-size: 100%; + background-color: #11303d; + color: #000; + margin: 0; + padding: 0; +} + +div.document { + background-color: #1c4e63; +} + +div.documentwrapper { + float: left; + width: 100%; +} + +div.bodywrapper { + margin: 0 0 0 230px; +} + +div.body { + background-color: #ffffff; + color: #000000; + padding: 0 20px 30px 20px; +} + +div.footer { + color: #ffffff; + width: 100%; + padding: 9px 0 9px 0; + text-align: center; + font-size: 75%; +} + +div.footer a { + color: #ffffff; + text-decoration: underline; +} + +div.related { + background-color: #133f52; + line-height: 30px; + color: #ffffff; +} + +div.related a { + color: #ffffff; +} + +div.sphinxsidebar { +} + +div.sphinxsidebar h3 { + font-family: 'Trebuchet MS', sans-serif; + color: #ffffff; + font-size: 1.4em; + font-weight: normal; + margin: 0; + padding: 0; +} + +div.sphinxsidebar h3 a { + color: #ffffff; +} + +div.sphinxsidebar h4 { + font-family: 'Trebuchet MS', sans-serif; + color: #ffffff; + font-size: 1.3em; + font-weight: normal; + margin: 5px 0 0 0; + padding: 0; +} + +div.sphinxsidebar p { + color: #ffffff; +} + +div.sphinxsidebar p.topless { + margin: 5px 10px 10px 10px; +} + +div.sphinxsidebar ul { + margin: 10px; + padding: 0; + color: #ffffff; +} + +div.sphinxsidebar a { + color: #98dbcc; +} + +div.sphinxsidebar input { + border: 1px solid #98dbcc; + font-family: sans-serif; + font-size: 1em; +} + +/* -- body styles ----------------------------------------------------------- */ + +a { + color: #355f7c; + text-decoration: none; +} + +a:hover { + text-decoration: underline; +} + +div.body p, div.body dd, div.body li { + text-align: justify; + line-height: 130%; +} + +div.body h1, +div.body h2, +div.body h3, +div.body h4, +div.body h5, +div.body h6 { + font-family: 'Trebuchet MS', sans-serif; + background-color: #f2f2f2; + font-weight: normal; + color: #20435c; + border-bottom: 1px solid #ccc; + margin: 20px -20px 10px -20px; + padding: 3px 0 3px 10px; +} + +div.body h1 { margin-top: 0; font-size: 200%; } +div.body h2 { font-size: 160%; } +div.body h3 { font-size: 140%; } +div.body h4 { font-size: 120%; } +div.body h5 { font-size: 110%; } +div.body h6 { font-size: 100%; } + +a.headerlink { + color: #c60f0f; + font-size: 0.8em; + padding: 0 4px 0 4px; + text-decoration: none; +} + +a.headerlink:hover { + background-color: #c60f0f; + color: white; +} + +div.body p, div.body dd, div.body li { + text-align: justify; + line-height: 130%; +} + +div.admonition p.admonition-title + p { + display: inline; +} + +div.note { + background-color: #eee; + border: 1px solid #ccc; +} + +div.seealso { + background-color: #ffc; + border: 1px solid #ff6; +} + +div.topic { + background-color: #eee; +} + +div.warning { + background-color: #ffe4e4; + border: 1px solid #f66; +} + +p.admonition-title { + display: inline; +} + +p.admonition-title:after { + content: ":"; +} + +pre { + padding: 5px; + background-color: #eeffcc; + color: #333333; + line-height: 120%; + border: 1px solid #ac9; + border-left: none; + border-right: none; +} + +tt { + background-color: #ecf0f3; + padding: 0 1px 0 1px; + font-size: 0.95em; +} + +.warning tt { + background: #efc2c2; +} + +.note tt { + background: #d6d6d6; +}
\ No newline at end of file diff --git a/doc/html/_static/doctools.js b/doc/html/_static/doctools.js new file mode 100644 index 0000000..9447678 --- /dev/null +++ b/doc/html/_static/doctools.js @@ -0,0 +1,232 @@ +/// XXX: make it cross browser + +/** + * make the code below compatible with browsers without + * an installed firebug like debugger + */ +if (!window.console || !console.firebug) { + var names = ["log", "debug", "info", "warn", "error", "assert", "dir", "dirxml", + "group", "groupEnd", "time", "timeEnd", "count", "trace", "profile", "profileEnd"]; + window.console = {}; + for (var i = 0; i < names.length; ++i) + window.console[names[i]] = function() {} +} + +/** + * small helper function to urldecode strings + */ +jQuery.urldecode = function(x) { + return decodeURIComponent(x).replace(/\+/g, ' '); +} + +/** + * small helper function to urlencode strings + */ +jQuery.urlencode = encodeURIComponent; + +/** + * This function returns the parsed url parameters of the + * current request. Multiple values per key are supported, + * it will always return arrays of strings for the value parts. + */ +jQuery.getQueryParameters = function(s) { + if (typeof s == 'undefined') + s = document.location.search; + var parts = s.substr(s.indexOf('?') + 1).split('&'); + var result = {}; + for (var i = 0; i < parts.length; i++) { + var tmp = parts[i].split('=', 2); + var key = jQuery.urldecode(tmp[0]); + var value = jQuery.urldecode(tmp[1]); + if (key in result) + result[key].push(value); + else + result[key] = [value]; + } + return result; +} + +/** + * small function to check if an array contains + * a given item. + */ +jQuery.contains = function(arr, item) { + for (var i = 0; i < arr.length; i++) { + if (arr[i] == item) + return true; + } + return false; +} + +/** + * highlight a given string on a jquery object by wrapping it in + * span elements with the given class name. + */ +jQuery.fn.highlightText = function(text, className) { + function highlight(node) { + if (node.nodeType == 3) { + var val = node.nodeValue; + var pos = val.toLowerCase().indexOf(text); + if (pos >= 0 && !jQuery.className.has(node.parentNode, className)) { + var span = document.createElement("span"); + span.className = className; + span.appendChild(document.createTextNode(val.substr(pos, text.length))); + node.parentNode.insertBefore(span, node.parentNode.insertBefore( + document.createTextNode(val.substr(pos + text.length)), + node.nextSibling)); + node.nodeValue = val.substr(0, pos); + } + } + else if (!jQuery(node).is("button, select, textarea")) { + jQuery.each(node.childNodes, function() { + highlight(this) + }); + } + } + return this.each(function() { + highlight(this); + }); +} + +/** + * Small JavaScript module for the documentation. + */ +var Documentation = { + + init : function() { + this.fixFirefoxAnchorBug(); + this.highlightSearchWords(); + this.initModIndex(); + }, + + /** + * i18n support + */ + TRANSLATIONS : {}, + PLURAL_EXPR : function(n) { return n == 1 ? 0 : 1; }, + LOCALE : 'unknown', + + // gettext and ngettext don't access this so that the functions + // can savely bound to a different name (_ = Documentation.gettext) + gettext : function(string) { + var translated = Documentation.TRANSLATIONS[string]; + if (typeof translated == 'undefined') + return string; + return (typeof translated == 'string') ? translated : translated[0]; + }, + + ngettext : function(singular, plural, n) { + var translated = Documentation.TRANSLATIONS[singular]; + if (typeof translated == 'undefined') + return (n == 1) ? singular : plural; + return translated[Documentation.PLURALEXPR(n)]; + }, + + addTranslations : function(catalog) { + for (var key in catalog.messages) + this.TRANSLATIONS[key] = catalog.messages[key]; + this.PLURAL_EXPR = new Function('n', 'return +(' + catalog.plural_expr + ')'); + this.LOCALE = catalog.locale; + }, + + /** + * add context elements like header anchor links + */ + addContextElements : function() { + $('div[id] > :header:first').each(function() { + $('<a class="headerlink">\u00B6</a>'). + attr('href', '#' + this.id). + attr('title', _('Permalink to this headline')). + appendTo(this); + }); + $('dt[id]').each(function() { + $('<a class="headerlink">\u00B6</a>'). + attr('href', '#' + this.id). + attr('title', _('Permalink to this definition')). + appendTo(this); + }); + }, + + /** + * workaround a firefox stupidity + */ + fixFirefoxAnchorBug : function() { + if (document.location.hash && $.browser.mozilla) + window.setTimeout(function() { + document.location.href += ''; + }, 10); + }, + + /** + * highlight the search words provided in the url in the text + */ + highlightSearchWords : function() { + var params = $.getQueryParameters(); + var terms = (params.highlight) ? params.highlight[0].split(/\s+/) : []; + if (terms.length) { + var body = $('div.body'); + window.setTimeout(function() { + $.each(terms, function() { + body.highlightText(this.toLowerCase(), 'highlight'); + }); + }, 10); + $('<li class="highlight-link"><a href="javascript:Documentation.' + + 'hideSearchWords()">' + _('Hide Search Matches') + '</a></li>') + .appendTo($('.sidebar .this-page-menu')); + } + }, + + /** + * init the modindex toggle buttons + */ + initModIndex : function() { + var togglers = $('img.toggler').click(function() { + var src = $(this).attr('src'); + var idnum = $(this).attr('id').substr(7); + console.log($('tr.cg-' + idnum).toggle()); + if (src.substr(-9) == 'minus.png') + $(this).attr('src', src.substr(0, src.length-9) + 'plus.png'); + else + $(this).attr('src', src.substr(0, src.length-8) + 'minus.png'); + }).css('display', ''); + if (DOCUMENTATION_OPTIONS.COLLAPSE_MODINDEX) { + togglers.click(); + } + }, + + /** + * helper function to hide the search marks again + */ + hideSearchWords : function() { + $('.sidebar .this-page-menu li.highlight-link').fadeOut(300); + $('span.highlight').removeClass('highlight'); + }, + + /** + * make the url absolute + */ + makeURL : function(relativeURL) { + return DOCUMENTATION_OPTIONS.URL_ROOT + '/' + relativeURL; + }, + + /** + * get the current relative url + */ + getCurrentURL : function() { + var path = document.location.pathname; + var parts = path.split(/\//); + $.each(DOCUMENTATION_OPTIONS.URL_ROOT.split(/\//), function() { + if (this == '..') + parts.pop(); + }); + var url = parts.join('/'); + return path.substring(url.lastIndexOf('/') + 1, path.length - 1); + } +}; + +// quick alias for translations +_ = Documentation.gettext; + +$(document).ready(function() { + Documentation.init(); +}); diff --git a/doc/html/_static/file.png b/doc/html/_static/file.png Binary files differnew file mode 100644 index 0000000..d18082e --- /dev/null +++ b/doc/html/_static/file.png diff --git a/doc/html/_static/jquery.js b/doc/html/_static/jquery.js new file mode 100644 index 0000000..9263574 --- /dev/null +++ b/doc/html/_static/jquery.js @@ -0,0 +1,4376 @@ +/*! + * jQuery JavaScript Library v1.3.2 + * http://jquery.com/ + * + * Copyright (c) 2009 John Resig + * Dual licensed under the MIT and GPL licenses. + * http://docs.jquery.com/License + * + * Date: 2009-02-19 17:34:21 -0500 (Thu, 19 Feb 2009) + * Revision: 6246 + */ +(function(){ + +var + // Will speed up references to window, and allows munging its name. + window = this, + // Will speed up references to undefined, and allows munging its name. + undefined, + // Map over jQuery in case of overwrite + _jQuery = window.jQuery, + // Map over the $ in case of overwrite + _$ = window.$, + + jQuery = window.jQuery = window.$ = function( selector, context ) { + // The jQuery object is actually just the init constructor 'enhanced' + return new jQuery.fn.init( selector, context ); + }, + + // A simple way to check for HTML strings or ID strings + // (both of which we optimize for) + quickExpr = /^[^<]*(<(.|\s)+>)[^>]*$|^#([\w-]+)$/, + // Is it a simple selector + isSimple = /^.[^:#\[\.,]*$/; + +jQuery.fn = jQuery.prototype = { + init: function( selector, context ) { + // Make sure that a selection was provided + selector = selector || document; + + // Handle $(DOMElement) + if ( selector.nodeType ) { + this[0] = selector; + this.length = 1; + this.context = selector; + return this; + } + // Handle HTML strings + if ( typeof selector === "string" ) { + // Are we dealing with HTML string or an ID? + var match = quickExpr.exec( selector ); + + // Verify a match, and that no context was specified for #id + if ( match && (match[1] || !context) ) { + + // HANDLE: $(html) -> $(array) + if ( match[1] ) + selector = jQuery.clean( [ match[1] ], context ); + + // HANDLE: $("#id") + else { + var elem = document.getElementById( match[3] ); + + // Handle the case where IE and Opera return items + // by name instead of ID + if ( elem && elem.id != match[3] ) + return jQuery().find( selector ); + + // Otherwise, we inject the element directly into the jQuery object + var ret = jQuery( elem || [] ); + ret.context = document; + ret.selector = selector; + return ret; + } + + // HANDLE: $(expr, [context]) + // (which is just equivalent to: $(content).find(expr) + } else + return jQuery( context ).find( selector ); + + // HANDLE: $(function) + // Shortcut for document ready + } else if ( jQuery.isFunction( selector ) ) + return jQuery( document ).ready( selector ); + + // Make sure that old selector state is passed along + if ( selector.selector && selector.context ) { + this.selector = selector.selector; + this.context = selector.context; + } + + return this.setArray(jQuery.isArray( selector ) ? + selector : + jQuery.makeArray(selector)); + }, + + // Start with an empty selector + selector: "", + + // The current version of jQuery being used + jquery: "1.3.2", + + // The number of elements contained in the matched element set + size: function() { + return this.length; + }, + + // Get the Nth element in the matched element set OR + // Get the whole matched element set as a clean array + get: function( num ) { + return num === undefined ? + + // Return a 'clean' array + Array.prototype.slice.call( this ) : + + // Return just the object + this[ num ]; + }, + + // Take an array of elements and push it onto the stack + // (returning the new matched element set) + pushStack: function( elems, name, selector ) { + // Build a new jQuery matched element set + var ret = jQuery( elems ); + + // Add the old object onto the stack (as a reference) + ret.prevObject = this; + + ret.context = this.context; + + if ( name === "find" ) + ret.selector = this.selector + (this.selector ? " " : "") + selector; + else if ( name ) + ret.selector = this.selector + "." + name + "(" + selector + ")"; + + // Return the newly-formed element set + return ret; + }, + + // Force the current matched set of elements to become + // the specified array of elements (destroying the stack in the process) + // You should use pushStack() in order to do this, but maintain the stack + setArray: function( elems ) { + // Resetting the length to 0, then using the native Array push + // is a super-fast way to populate an object with array-like properties + this.length = 0; + Array.prototype.push.apply( this, elems ); + + return this; + }, + + // Execute a callback for every element in the matched set. + // (You can seed the arguments with an array of args, but this is + // only used internally.) + each: function( callback, args ) { + return jQuery.each( this, callback, args ); + }, + + // Determine the position of an element within + // the matched set of elements + index: function( elem ) { + // Locate the position of the desired element + return jQuery.inArray( + // If it receives a jQuery object, the first element is used + elem && elem.jquery ? elem[0] : elem + , this ); + }, + + attr: function( name, value, type ) { + var options = name; + + // Look for the case where we're accessing a style value + if ( typeof name === "string" ) + if ( value === undefined ) + return this[0] && jQuery[ type || "attr" ]( this[0], name ); + + else { + options = {}; + options[ name ] = value; + } + + // Check to see if we're setting style values + return this.each(function(i){ + // Set all the styles + for ( name in options ) + jQuery.attr( + type ? + this.style : + this, + name, jQuery.prop( this, options[ name ], type, i, name ) + ); + }); + }, + + css: function( key, value ) { + // ignore negative width and height values + if ( (key == 'width' || key == 'height') && parseFloat(value) < 0 ) + value = undefined; + return this.attr( key, value, "curCSS" ); + }, + + text: function( text ) { + if ( typeof text !== "object" && text != null ) + return this.empty().append( (this[0] && this[0].ownerDocument || document).createTextNode( text ) ); + + var ret = ""; + + jQuery.each( text || this, function(){ + jQuery.each( this.childNodes, function(){ + if ( this.nodeType != 8 ) + ret += this.nodeType != 1 ? + this.nodeValue : + jQuery.fn.text( [ this ] ); + }); + }); + + return ret; + }, + + wrapAll: function( html ) { + if ( this[0] ) { + // The elements to wrap the target around + var wrap = jQuery( html, this[0].ownerDocument ).clone(); + + if ( this[0].parentNode ) + wrap.insertBefore( this[0] ); + + wrap.map(function(){ + var elem = this; + + while ( elem.firstChild ) + elem = elem.firstChild; + + return elem; + }).append(this); + } + + return this; + }, + + wrapInner: function( html ) { + return this.each(function(){ + jQuery( this ).contents().wrapAll( html ); + }); + }, + + wrap: function( html ) { + return this.each(function(){ + jQuery( this ).wrapAll( html ); + }); + }, + + append: function() { + return this.domManip(arguments, true, function(elem){ + if (this.nodeType == 1) + this.appendChild( elem ); + }); + }, + + prepend: function() { + return this.domManip(arguments, true, function(elem){ + if (this.nodeType == 1) + this.insertBefore( elem, this.firstChild ); + }); + }, + + before: function() { + return this.domManip(arguments, false, function(elem){ + this.parentNode.insertBefore( elem, this ); + }); + }, + + after: function() { + return this.domManip(arguments, false, function(elem){ + this.parentNode.insertBefore( elem, this.nextSibling ); + }); + }, + + end: function() { + return this.prevObject || jQuery( [] ); + }, + + // For internal use only. + // Behaves like an Array's method, not like a jQuery method. + push: [].push, + sort: [].sort, + splice: [].splice, + + find: function( selector ) { + if ( this.length === 1 ) { + var ret = this.pushStack( [], "find", selector ); + ret.length = 0; + jQuery.find( selector, this[0], ret ); + return ret; + } else { + return this.pushStack( jQuery.unique(jQuery.map(this, function(elem){ + return jQuery.find( selector, elem ); + })), "find", selector ); + } + }, + + clone: function( events ) { + // Do the clone + var ret = this.map(function(){ + if ( !jQuery.support.noCloneEvent && !jQuery.isXMLDoc(this) ) { + // IE copies events bound via attachEvent when + // using cloneNode. Calling detachEvent on the + // clone will also remove the events from the orignal + // In order to get around this, we use innerHTML. + // Unfortunately, this means some modifications to + // attributes in IE that are actually only stored + // as properties will not be copied (such as the + // the name attribute on an input). + var html = this.outerHTML; + if ( !html ) { + var div = this.ownerDocument.createElement("div"); + div.appendChild( this.cloneNode(true) ); + html = div.innerHTML; + } + + return jQuery.clean([html.replace(/ jQuery\d+="(?:\d+|null)"/g, "").replace(/^\s*/, "")])[0]; + } else + return this.cloneNode(true); + }); + + // Copy the events from the original to the clone + if ( events === true ) { + var orig = this.find("*").andSelf(), i = 0; + + ret.find("*").andSelf().each(function(){ + if ( this.nodeName !== orig[i].nodeName ) + return; + + var events = jQuery.data( orig[i], "events" ); + + for ( var type in events ) { + for ( var handler in events[ type ] ) { + jQuery.event.add( this, type, events[ type ][ handler ], events[ type ][ handler ].data ); + } + } + + i++; + }); + } + + // Return the cloned set + return ret; + }, + + filter: function( selector ) { + return this.pushStack( + jQuery.isFunction( selector ) && + jQuery.grep(this, function(elem, i){ + return selector.call( elem, i ); + }) || + + jQuery.multiFilter( selector, jQuery.grep(this, function(elem){ + return elem.nodeType === 1; + }) ), "filter", selector ); + }, + + closest: function( selector ) { + var pos = jQuery.expr.match.POS.test( selector ) ? jQuery(selector) : null, + closer = 0; + + return this.map(function(){ + var cur = this; + while ( cur && cur.ownerDocument ) { + if ( pos ? pos.index(cur) > -1 : jQuery(cur).is(selector) ) { + jQuery.data(cur, "closest", closer); + return cur; + } + cur = cur.parentNode; + closer++; + } + }); + }, + + not: function( selector ) { + if ( typeof selector === "string" ) + // test special case where just one selector is passed in + if ( isSimple.test( selector ) ) + return this.pushStack( jQuery.multiFilter( selector, this, true ), "not", selector ); + else + selector = jQuery.multiFilter( selector, this ); + + var isArrayLike = selector.length && selector[selector.length - 1] !== undefined && !selector.nodeType; + return this.filter(function() { + return isArrayLike ? jQuery.inArray( this, selector ) < 0 : this != selector; + }); + }, + + add: function( selector ) { + return this.pushStack( jQuery.unique( jQuery.merge( + this.get(), + typeof selector === "string" ? + jQuery( selector ) : + jQuery.makeArray( selector ) + ))); + }, + + is: function( selector ) { + return !!selector && jQuery.multiFilter( selector, this ).length > 0; + }, + + hasClass: function( selector ) { + return !!selector && this.is( "." + selector ); + }, + + val: function( value ) { + if ( value === undefined ) { + var elem = this[0]; + + if ( elem ) { + if( jQuery.nodeName( elem, 'option' ) ) + return (elem.attributes.value || {}).specified ? elem.value : elem.text; + + // We need to handle select boxes special + if ( jQuery.nodeName( elem, "select" ) ) { + var index = elem.selectedIndex, + values = [], + options = elem.options, + one = elem.type == "select-one"; + + // Nothing was selected + if ( index < 0 ) + return null; + + // Loop through all the selected options + for ( var i = one ? index : 0, max = one ? index + 1 : options.length; i < max; i++ ) { + var option = options[ i ]; + + if ( option.selected ) { + // Get the specifc value for the option + value = jQuery(option).val(); + + // We don't need an array for one selects + if ( one ) + return value; + + // Multi-Selects return an array + values.push( value ); + } + } + + return values; + } + + // Everything else, we just grab the value + return (elem.value || "").replace(/\r/g, ""); + + } + + return undefined; + } + + if ( typeof value === "number" ) + value += ''; + + return this.each(function(){ + if ( this.nodeType != 1 ) + return; + + if ( jQuery.isArray(value) && /radio|checkbox/.test( this.type ) ) + this.checked = (jQuery.inArray(this.value, value) >= 0 || + jQuery.inArray(this.name, value) >= 0); + + else if ( jQuery.nodeName( this, "select" ) ) { + var values = jQuery.makeArray(value); + + jQuery( "option", this ).each(function(){ + this.selected = (jQuery.inArray( this.value, values ) >= 0 || + jQuery.inArray( this.text, values ) >= 0); + }); + + if ( !values.length ) + this.selectedIndex = -1; + + } else + this.value = value; + }); + }, + + html: function( value ) { + return value === undefined ? + (this[0] ? + this[0].innerHTML.replace(/ jQuery\d+="(?:\d+|null)"/g, "") : + null) : + this.empty().append( value ); + }, + + replaceWith: function( value ) { + return this.after( value ).remove(); + }, + + eq: function( i ) { + return this.slice( i, +i + 1 ); + }, + + slice: function() { + return this.pushStack( Array.prototype.slice.apply( this, arguments ), + "slice", Array.prototype.slice.call(arguments).join(",") ); + }, + + map: function( callback ) { + return this.pushStack( jQuery.map(this, function(elem, i){ + return callback.call( elem, i, elem ); + })); + }, + + andSelf: function() { + return this.add( this.prevObject ); + }, + + domManip: function( args, table, callback ) { + if ( this[0] ) { + var fragment = (this[0].ownerDocument || this[0]).createDocumentFragment(), + scripts = jQuery.clean( args, (this[0].ownerDocument || this[0]), fragment ), + first = fragment.firstChild; + + if ( first ) + for ( var i = 0, l = this.length; i < l; i++ ) + callback.call( root(this[i], first), this.length > 1 || i > 0 ? + fragment.cloneNode(true) : fragment ); + + if ( scripts ) + jQuery.each( scripts, evalScript ); + } + + return this; + + function root( elem, cur ) { + return table && jQuery.nodeName(elem, "table") && jQuery.nodeName(cur, "tr") ? + (elem.getElementsByTagName("tbody")[0] || + elem.appendChild(elem.ownerDocument.createElement("tbody"))) : + elem; + } + } +}; + +// Give the init function the jQuery prototype for later instantiation +jQuery.fn.init.prototype = jQuery.fn; + +function evalScript( i, elem ) { + if ( elem.src ) + jQuery.ajax({ + url: elem.src, + async: false, + dataType: "script" + }); + + else + jQuery.globalEval( elem.text || elem.textContent || elem.innerHTML || "" ); + + if ( elem.parentNode ) + elem.parentNode.removeChild( elem ); +} + +function now(){ + return +new Date; +} + +jQuery.extend = jQuery.fn.extend = function() { + // copy reference to target object + var target = arguments[0] || {}, i = 1, length = arguments.length, deep = false, options; + + // Handle a deep copy situation + if ( typeof target === "boolean" ) { + deep = target; + target = arguments[1] || {}; + // skip the boolean and the target + i = 2; + } + + // Handle case when target is a string or something (possible in deep copy) + if ( typeof target !== "object" && !jQuery.isFunction(target) ) + target = {}; + + // extend jQuery itself if only one argument is passed + if ( length == i ) { + target = this; + --i; + } + + for ( ; i < length; i++ ) + // Only deal with non-null/undefined values + if ( (options = arguments[ i ]) != null ) + // Extend the base object + for ( var name in options ) { + var src = target[ name ], copy = options[ name ]; + + // Prevent never-ending loop + if ( target === copy ) + continue; + + // Recurse if we're merging object values + if ( deep && copy && typeof copy === "object" && !copy.nodeType ) + target[ name ] = jQuery.extend( deep, + // Never move original objects, clone them + src || ( copy.length != null ? [ ] : { } ) + , copy ); + + // Don't bring in undefined values + else if ( copy !== undefined ) + target[ name ] = copy; + + } + + // Return the modified object + return target; +}; + +// exclude the following css properties to add px +var exclude = /z-?index|font-?weight|opacity|zoom|line-?height/i, + // cache defaultView + defaultView = document.defaultView || {}, + toString = Object.prototype.toString; + +jQuery.extend({ + noConflict: function( deep ) { + window.$ = _$; + + if ( deep ) + window.jQuery = _jQuery; + + return jQuery; + }, + + // See test/unit/core.js for details concerning isFunction. + // Since version 1.3, DOM methods and functions like alert + // aren't supported. They return false on IE (#2968). + isFunction: function( obj ) { + return toString.call(obj) === "[object Function]"; + }, + + isArray: function( obj ) { + return toString.call(obj) === "[object Array]"; + }, + + // check if an element is in a (or is an) XML document + isXMLDoc: function( elem ) { + return elem.nodeType === 9 && elem.documentElement.nodeName !== "HTML" || + !!elem.ownerDocument && jQuery.isXMLDoc( elem.ownerDocument ); + }, + + // Evalulates a script in a global context + globalEval: function( data ) { + if ( data && /\S/.test(data) ) { + // Inspired by code by Andrea Giammarchi + // http://webreflection.blogspot.com/2007/08/global-scope-evaluation-and-dom.html + var head = document.getElementsByTagName("head")[0] || document.documentElement, + script = document.createElement("script"); + + script.type = "text/javascript"; + if ( jQuery.support.scriptEval ) + script.appendChild( document.createTextNode( data ) ); + else + script.text = data; + + // Use insertBefore instead of appendChild to circumvent an IE6 bug. + // This arises when a base node is used (#2709). + head.insertBefore( script, head.firstChild ); + head.removeChild( script ); + } + }, + + nodeName: function( elem, name ) { + return elem.nodeName && elem.nodeName.toUpperCase() == name.toUpperCase(); + }, + + // args is for internal usage only + each: function( object, callback, args ) { + var name, i = 0, length = object.length; + + if ( args ) { + if ( length === undefined ) { + for ( name in object ) + if ( callback.apply( object[ name ], args ) === false ) + break; + } else + for ( ; i < length; ) + if ( callback.apply( object[ i++ ], args ) === false ) + break; + + // A special, fast, case for the most common use of each + } else { + if ( length === undefined ) { + for ( name in object ) + if ( callback.call( object[ name ], name, object[ name ] ) === false ) + break; + } else + for ( var value = object[0]; + i < length && callback.call( value, i, value ) !== false; value = object[++i] ){} + } + + return object; + }, + + prop: function( elem, value, type, i, name ) { + // Handle executable functions + if ( jQuery.isFunction( value ) ) + value = value.call( elem, i ); + + // Handle passing in a number to a CSS property + return typeof value === "number" && type == "curCSS" && !exclude.test( name ) ? + value + "px" : + value; + }, + + className: { + // internal only, use addClass("class") + add: function( elem, classNames ) { + jQuery.each((classNames || "").split(/\s+/), function(i, className){ + if ( elem.nodeType == 1 && !jQuery.className.has( elem.className, className ) ) + elem.className += (elem.className ? " " : "") + className; + }); + }, + + // internal only, use removeClass("class") + remove: function( elem, classNames ) { + if (elem.nodeType == 1) + elem.className = classNames !== undefined ? + jQuery.grep(elem.className.split(/\s+/), function(className){ + return !jQuery.className.has( classNames, className ); + }).join(" ") : + ""; + }, + + // internal only, use hasClass("class") + has: function( elem, className ) { + return elem && jQuery.inArray( className, (elem.className || elem).toString().split(/\s+/) ) > -1; + } + }, + + // A method for quickly swapping in/out CSS properties to get correct calculations + swap: function( elem, options, callback ) { + var old = {}; + // Remember the old values, and insert the new ones + for ( var name in options ) { + old[ name ] = elem.style[ name ]; + elem.style[ name ] = options[ name ]; + } + + callback.call( elem ); + + // Revert the old values + for ( var name in options ) + elem.style[ name ] = old[ name ]; + }, + + css: function( elem, name, force, extra ) { + if ( name == "width" || name == "height" ) { + var val, props = { position: "absolute", visibility: "hidden", display:"block" }, which = name == "width" ? [ "Left", "Right" ] : [ "Top", "Bottom" ]; + + function getWH() { + val = name == "width" ? elem.offsetWidth : elem.offsetHeight; + + if ( extra === "border" ) + return; + + jQuery.each( which, function() { + if ( !extra ) + val -= parseFloat(jQuery.curCSS( elem, "padding" + this, true)) || 0; + if ( extra === "margin" ) + val += parseFloat(jQuery.curCSS( elem, "margin" + this, true)) || 0; + else + val -= parseFloat(jQuery.curCSS( elem, "border" + this + "Width", true)) || 0; + }); + } + + if ( elem.offsetWidth !== 0 ) + getWH(); + else + jQuery.swap( elem, props, getWH ); + + return Math.max(0, Math.round(val)); + } + + return jQuery.curCSS( elem, name, force ); + }, + + curCSS: function( elem, name, force ) { + var ret, style = elem.style; + + // We need to handle opacity special in IE + if ( name == "opacity" && !jQuery.support.opacity ) { + ret = jQuery.attr( style, "opacity" ); + + return ret == "" ? + "1" : + ret; + } + + // Make sure we're using the right name for getting the float value + if ( name.match( /float/i ) ) + name = styleFloat; + + if ( !force && style && style[ name ] ) + ret = style[ name ]; + + else if ( defaultView.getComputedStyle ) { + + // Only "float" is needed here + if ( name.match( /float/i ) ) + name = "float"; + + name = name.replace( /([A-Z])/g, "-$1" ).toLowerCase(); + + var computedStyle = defaultView.getComputedStyle( elem, null ); + + if ( computedStyle ) + ret = computedStyle.getPropertyValue( name ); + + // We should always get a number back from opacity + if ( name == "opacity" && ret == "" ) + ret = "1"; + + } else if ( elem.currentStyle ) { + var camelCase = name.replace(/\-(\w)/g, function(all, letter){ + return letter.toUpperCase(); + }); + + ret = elem.currentStyle[ name ] || elem.currentStyle[ camelCase ]; + + // From the awesome hack by Dean Edwards + // http://erik.eae.net/archives/2007/07/27/18.54.15/#comment-102291 + + // If we're not dealing with a regular pixel number + // but a number that has a weird ending, we need to convert it to pixels + if ( !/^\d+(px)?$/i.test( ret ) && /^\d/.test( ret ) ) { + // Remember the original values + var left = style.left, rsLeft = elem.runtimeStyle.left; + + // Put in the new values to get a computed value out + elem.runtimeStyle.left = elem.currentStyle.left; + style.left = ret || 0; + ret = style.pixelLeft + "px"; + + // Revert the changed values + style.left = left; + elem.runtimeStyle.left = rsLeft; + } + } + + return ret; + }, + + clean: function( elems, context, fragment ) { + context = context || document; + + // !context.createElement fails in IE with an error but returns typeof 'object' + if ( typeof context.createElement === "undefined" ) + context = context.ownerDocument || context[0] && context[0].ownerDocument || document; + + // If a single string is passed in and it's a single tag + // just do a createElement and skip the rest + if ( !fragment && elems.length === 1 && typeof elems[0] === "string" ) { + var match = /^<(\w+)\s*\/?>$/.exec(elems[0]); + if ( match ) + return [ context.createElement( match[1] ) ]; + } + + var ret = [], scripts = [], div = context.createElement("div"); + + jQuery.each(elems, function(i, elem){ + if ( typeof elem === "number" ) + elem += ''; + + if ( !elem ) + return; + + // Convert html string into DOM nodes + if ( typeof elem === "string" ) { + // Fix "XHTML"-style tags in all browsers + elem = elem.replace(/(<(\w+)[^>]*?)\/>/g, function(all, front, tag){ + return tag.match(/^(abbr|br|col|img|input|link|meta|param|hr|area|embed)$/i) ? + all : + front + "></" + tag + ">"; + }); + + // Trim whitespace, otherwise indexOf won't work as expected + var tags = elem.replace(/^\s+/, "").substring(0, 10).toLowerCase(); + + var wrap = + // option or optgroup + !tags.indexOf("<opt") && + [ 1, "<select multiple='multiple'>", "</select>" ] || + + !tags.indexOf("<leg") && + [ 1, "<fieldset>", "</fieldset>" ] || + + tags.match(/^<(thead|tbody|tfoot|colg|cap)/) && + [ 1, "<table>", "</table>" ] || + + !tags.indexOf("<tr") && + [ 2, "<table><tbody>", "</tbody></table>" ] || + + // <thead> matched above + (!tags.indexOf("<td") || !tags.indexOf("<th")) && + [ 3, "<table><tbody><tr>", "</tr></tbody></table>" ] || + + !tags.indexOf("<col") && + [ 2, "<table><tbody></tbody><colgroup>", "</colgroup></table>" ] || + + // IE can't serialize <link> and <script> tags normally + !jQuery.support.htmlSerialize && + [ 1, "div<div>", "</div>" ] || + + [ 0, "", "" ]; + + // Go to html and back, then peel off extra wrappers + div.innerHTML = wrap[1] + elem + wrap[2]; + + // Move to the right depth + while ( wrap[0]-- ) + div = div.lastChild; + + // Remove IE's autoinserted <tbody> from table fragments + if ( !jQuery.support.tbody ) { + + // String was a <table>, *may* have spurious <tbody> + var hasBody = /<tbody/i.test(elem), + tbody = !tags.indexOf("<table") && !hasBody ? + div.firstChild && div.firstChild.childNodes : + + // String was a bare <thead> or <tfoot> + wrap[1] == "<table>" && !hasBody ? + div.childNodes : + []; + + for ( var j = tbody.length - 1; j >= 0 ; --j ) + if ( jQuery.nodeName( tbody[ j ], "tbody" ) && !tbody[ j ].childNodes.length ) + tbody[ j ].parentNode.removeChild( tbody[ j ] ); + + } + + // IE completely kills leading whitespace when innerHTML is used + if ( !jQuery.support.leadingWhitespace && /^\s/.test( elem ) ) + div.insertBefore( context.createTextNode( elem.match(/^\s*/)[0] ), div.firstChild ); + + elem = jQuery.makeArray( div.childNodes ); + } + + if ( elem.nodeType ) + ret.push( elem ); + else + ret = jQuery.merge( ret, elem ); + + }); + + if ( fragment ) { + for ( var i = 0; ret[i]; i++ ) { + if ( jQuery.nodeName( ret[i], "script" ) && (!ret[i].type || ret[i].type.toLowerCase() === "text/javascript") ) { + scripts.push( ret[i].parentNode ? ret[i].parentNode.removeChild( ret[i] ) : ret[i] ); + } else { + if ( ret[i].nodeType === 1 ) + ret.splice.apply( ret, [i + 1, 0].concat(jQuery.makeArray(ret[i].getElementsByTagName("script"))) ); + fragment.appendChild( ret[i] ); + } + } + + return scripts; + } + + return ret; + }, + + attr: function( elem, name, value ) { + // don't set attributes on text and comment nodes + if (!elem || elem.nodeType == 3 || elem.nodeType == 8) + return undefined; + + var notxml = !jQuery.isXMLDoc( elem ), + // Whether we are setting (or getting) + set = value !== undefined; + + // Try to normalize/fix the name + name = notxml && jQuery.props[ name ] || name; + + // Only do all the following if this is a node (faster for style) + // IE elem.getAttribute passes even for style + if ( elem.tagName ) { + + // These attributes require special treatment + var special = /href|src|style/.test( name ); + + // Safari mis-reports the default selected property of a hidden option + // Accessing the parent's selectedIndex property fixes it + if ( name == "selected" && elem.parentNode ) + elem.parentNode.selectedIndex; + + // If applicable, access the attribute via the DOM 0 way + if ( name in elem && notxml && !special ) { + if ( set ){ + // We can't allow the type property to be changed (since it causes problems in IE) + if ( name == "type" && jQuery.nodeName( elem, "input" ) && elem.parentNode ) + throw "type property can't be changed"; + + elem[ name ] = value; + } + + // browsers index elements by id/name on forms, give priority to attributes. + if( jQuery.nodeName( elem, "form" ) && elem.getAttributeNode(name) ) + return elem.getAttributeNode( name ).nodeValue; + + // elem.tabIndex doesn't always return the correct value when it hasn't been explicitly set + // http://fluidproject.org/blog/2008/01/09/getting-setting-and-removing-tabindex-values-with-javascript/ + if ( name == "tabIndex" ) { + var attributeNode = elem.getAttributeNode( "tabIndex" ); + return attributeNode && attributeNode.specified + ? attributeNode.value + : elem.nodeName.match(/(button|input|object|select|textarea)/i) + ? 0 + : elem.nodeName.match(/^(a|area)$/i) && elem.href + ? 0 + : undefined; + } + + return elem[ name ]; + } + + if ( !jQuery.support.style && notxml && name == "style" ) + return jQuery.attr( elem.style, "cssText", value ); + + if ( set ) + // convert the value to a string (all browsers do this but IE) see #1070 + elem.setAttribute( name, "" + value ); + + var attr = !jQuery.support.hrefNormalized && notxml && special + // Some attributes require a special call on IE + ? elem.getAttribute( name, 2 ) + : elem.getAttribute( name ); + + // Non-existent attributes return null, we normalize to undefined + return attr === null ? undefined : attr; + } + + // elem is actually elem.style ... set the style + + // IE uses filters for opacity + if ( !jQuery.support.opacity && name == "opacity" ) { + if ( set ) { + // IE has trouble with opacity if it does not have layout + // Force it by setting the zoom level + elem.zoom = 1; + + // Set the alpha filter to set the opacity + elem.filter = (elem.filter || "").replace( /alpha\([^)]*\)/, "" ) + + (parseInt( value ) + '' == "NaN" ? "" : "alpha(opacity=" + value * 100 + ")"); + } + + return elem.filter && elem.filter.indexOf("opacity=") >= 0 ? + (parseFloat( elem.filter.match(/opacity=([^)]*)/)[1] ) / 100) + '': + ""; + } + + name = name.replace(/-([a-z])/ig, function(all, letter){ + return letter.toUpperCase(); + }); + + if ( set ) + elem[ name ] = value; + + return elem[ name ]; + }, + + trim: function( text ) { + return (text || "").replace( /^\s+|\s+$/g, "" ); + }, + + makeArray: function( array ) { + var ret = []; + + if( array != null ){ + var i = array.length; + // The window, strings (and functions) also have 'length' + if( i == null || typeof array === "string" || jQuery.isFunction(array) || array.setInterval ) + ret[0] = array; + else + while( i ) + ret[--i] = array[i]; + } + + return ret; + }, + + inArray: function( elem, array ) { + for ( var i = 0, length = array.length; i < length; i++ ) + // Use === because on IE, window == document + if ( array[ i ] === elem ) + return i; + + return -1; + }, + + merge: function( first, second ) { + // We have to loop this way because IE & Opera overwrite the length + // expando of getElementsByTagName + var i = 0, elem, pos = first.length; + // Also, we need to make sure that the correct elements are being returned + // (IE returns comment nodes in a '*' query) + if ( !jQuery.support.getAll ) { + while ( (elem = second[ i++ ]) != null ) + if ( elem.nodeType != 8 ) + first[ pos++ ] = elem; + + } else + while ( (elem = second[ i++ ]) != null ) + first[ pos++ ] = elem; + + return first; + }, + + unique: function( array ) { + var ret = [], done = {}; + + try { + + for ( var i = 0, length = array.length; i < length; i++ ) { + var id = jQuery.data( array[ i ] ); + + if ( !done[ id ] ) { + done[ id ] = true; + ret.push( array[ i ] ); + } + } + + } catch( e ) { + ret = array; + } + + return ret; + }, + + grep: function( elems, callback, inv ) { + var ret = []; + + // Go through the array, only saving the items + // that pass the validator function + for ( var i = 0, length = elems.length; i < length; i++ ) + if ( !inv != !callback( elems[ i ], i ) ) + ret.push( elems[ i ] ); + + return ret; + }, + + map: function( elems, callback ) { + var ret = []; + + // Go through the array, translating each of the items to their + // new value (or values). + for ( var i = 0, length = elems.length; i < length; i++ ) { + var value = callback( elems[ i ], i ); + + if ( value != null ) + ret[ ret.length ] = value; + } + + return ret.concat.apply( [], ret ); + } +}); + +// Use of jQuery.browser is deprecated. +// It's included for backwards compatibility and plugins, +// although they should work to migrate away. + +var userAgent = navigator.userAgent.toLowerCase(); + +// Figure out what browser is being used +jQuery.browser = { + version: (userAgent.match( /.+(?:rv|it|ra|ie)[\/: ]([\d.]+)/ ) || [0,'0'])[1], + safari: /webkit/.test( userAgent ), + opera: /opera/.test( userAgent ), + msie: /msie/.test( userAgent ) && !/opera/.test( userAgent ), + mozilla: /mozilla/.test( userAgent ) && !/(compatible|webkit)/.test( userAgent ) +}; + +jQuery.each({ + parent: function(elem){return elem.parentNode;}, + parents: function(elem){return jQuery.dir(elem,"parentNode");}, + next: function(elem){return jQuery.nth(elem,2,"nextSibling");}, + prev: function(elem){return jQuery.nth(elem,2,"previousSibling");}, + nextAll: function(elem){return jQuery.dir(elem,"nextSibling");}, + prevAll: function(elem){return jQuery.dir(elem,"previousSibling");}, + siblings: function(elem){return jQuery.sibling(elem.parentNode.firstChild,elem);}, + children: function(elem){return jQuery.sibling(elem.firstChild);}, + contents: function(elem){return jQuery.nodeName(elem,"iframe")?elem.contentDocument||elem.contentWindow.document:jQuery.makeArray(elem.childNodes);} +}, function(name, fn){ + jQuery.fn[ name ] = function( selector ) { + var ret = jQuery.map( this, fn ); + + if ( selector && typeof selector == "string" ) + ret = jQuery.multiFilter( selector, ret ); + + return this.pushStack( jQuery.unique( ret ), name, selector ); + }; +}); + +jQuery.each({ + appendTo: "append", + prependTo: "prepend", + insertBefore: "before", + insertAfter: "after", + replaceAll: "replaceWith" +}, function(name, original){ + jQuery.fn[ name ] = function( selector ) { + var ret = [], insert = jQuery( selector ); + + for ( var i = 0, l = insert.length; i < l; i++ ) { + var elems = (i > 0 ? this.clone(true) : this).get(); + jQuery.fn[ original ].apply( jQuery(insert[i]), elems ); + ret = ret.concat( elems ); + } + + return this.pushStack( ret, name, selector ); + }; +}); + +jQuery.each({ + removeAttr: function( name ) { + jQuery.attr( this, name, "" ); + if (this.nodeType == 1) + this.removeAttribute( name ); + }, + + addClass: function( classNames ) { + jQuery.className.add( this, classNames ); + }, + + removeClass: function( classNames ) { + jQuery.className.remove( this, classNames ); + }, + + toggleClass: function( classNames, state ) { + if( typeof state !== "boolean" ) + state = !jQuery.className.has( this, classNames ); + jQuery.className[ state ? "add" : "remove" ]( this, classNames ); + }, + + remove: function( selector ) { + if ( !selector || jQuery.filter( selector, [ this ] ).length ) { + // Prevent memory leaks + jQuery( "*", this ).add([this]).each(function(){ + jQuery.event.remove(this); + jQuery.removeData(this); + }); + if (this.parentNode) + this.parentNode.removeChild( this ); + } + }, + + empty: function() { + // Remove element nodes and prevent memory leaks + jQuery(this).children().remove(); + + // Remove any remaining nodes + while ( this.firstChild ) + this.removeChild( this.firstChild ); + } +}, function(name, fn){ + jQuery.fn[ name ] = function(){ + return this.each( fn, arguments ); + }; +}); + +// Helper function used by the dimensions and offset modules +function num(elem, prop) { + return elem[0] && parseInt( jQuery.curCSS(elem[0], prop, true), 10 ) || 0; +} +var expando = "jQuery" + now(), uuid = 0, windowData = {};
+
+jQuery.extend({
+ cache: {},
+
+ data: function( elem, name, data ) {
+ elem = elem == window ?
+ windowData :
+ elem;
+
+ var id = elem[ expando ];
+
+ // Compute a unique ID for the element
+ if ( !id )
+ id = elem[ expando ] = ++uuid;
+
+ // Only generate the data cache if we're
+ // trying to access or manipulate it
+ if ( name && !jQuery.cache[ id ] )
+ jQuery.cache[ id ] = {};
+
+ // Prevent overriding the named cache with undefined values
+ if ( data !== undefined )
+ jQuery.cache[ id ][ name ] = data;
+
+ // Return the named cache data, or the ID for the element
+ return name ?
+ jQuery.cache[ id ][ name ] :
+ id;
+ },
+
+ removeData: function( elem, name ) {
+ elem = elem == window ?
+ windowData :
+ elem;
+
+ var id = elem[ expando ];
+
+ // If we want to remove a specific section of the element's data
+ if ( name ) {
+ if ( jQuery.cache[ id ] ) {
+ // Remove the section of cache data
+ delete jQuery.cache[ id ][ name ];
+
+ // If we've removed all the data, remove the element's cache
+ name = "";
+
+ for ( name in jQuery.cache[ id ] )
+ break;
+
+ if ( !name )
+ jQuery.removeData( elem );
+ }
+
+ // Otherwise, we want to remove all of the element's data
+ } else {
+ // Clean up the element expando
+ try {
+ delete elem[ expando ];
+ } catch(e){
+ // IE has trouble directly removing the expando
+ // but it's ok with using removeAttribute
+ if ( elem.removeAttribute )
+ elem.removeAttribute( expando );
+ }
+
+ // Completely remove the data cache
+ delete jQuery.cache[ id ];
+ }
+ },
+ queue: function( elem, type, data ) {
+ if ( elem ){
+
+ type = (type || "fx") + "queue";
+
+ var q = jQuery.data( elem, type );
+
+ if ( !q || jQuery.isArray(data) )
+ q = jQuery.data( elem, type, jQuery.makeArray(data) );
+ else if( data )
+ q.push( data );
+
+ }
+ return q;
+ },
+
+ dequeue: function( elem, type ){
+ var queue = jQuery.queue( elem, type ),
+ fn = queue.shift();
+
+ if( !type || type === "fx" )
+ fn = queue[0];
+
+ if( fn !== undefined )
+ fn.call(elem);
+ }
+});
+
+jQuery.fn.extend({
+ data: function( key, value ){
+ var parts = key.split(".");
+ parts[1] = parts[1] ? "." + parts[1] : "";
+
+ if ( value === undefined ) {
+ var data = this.triggerHandler("getData" + parts[1] + "!", [parts[0]]);
+
+ if ( data === undefined && this.length )
+ data = jQuery.data( this[0], key );
+
+ return data === undefined && parts[1] ?
+ this.data( parts[0] ) :
+ data;
+ } else
+ return this.trigger("setData" + parts[1] + "!", [parts[0], value]).each(function(){
+ jQuery.data( this, key, value );
+ });
+ },
+
+ removeData: function( key ){
+ return this.each(function(){
+ jQuery.removeData( this, key );
+ });
+ },
+ queue: function(type, data){
+ if ( typeof type !== "string" ) {
+ data = type;
+ type = "fx";
+ }
+
+ if ( data === undefined )
+ return jQuery.queue( this[0], type );
+
+ return this.each(function(){
+ var queue = jQuery.queue( this, type, data );
+
+ if( type == "fx" && queue.length == 1 )
+ queue[0].call(this);
+ });
+ },
+ dequeue: function(type){
+ return this.each(function(){
+ jQuery.dequeue( this, type );
+ });
+ }
+});/*! + * Sizzle CSS Selector Engine - v0.9.3 + * Copyright 2009, The Dojo Foundation + * Released under the MIT, BSD, and GPL Licenses. + * More information: http://sizzlejs.com/ + */ +(function(){ + +var chunker = /((?:\((?:\([^()]+\)|[^()]+)+\)|\[(?:\[[^[\]]*\]|['"][^'"]*['"]|[^[\]'"]+)+\]|\\.|[^ >+~,(\[\\]+)+|[>+~])(\s*,\s*)?/g, + done = 0, + toString = Object.prototype.toString; + +var Sizzle = function(selector, context, results, seed) { + results = results || []; + context = context || document; + + if ( context.nodeType !== 1 && context.nodeType !== 9 ) + return []; + + if ( !selector || typeof selector !== "string" ) { + return results; + } + + var parts = [], m, set, checkSet, check, mode, extra, prune = true; + + // Reset the position of the chunker regexp (start from head) + chunker.lastIndex = 0; + + while ( (m = chunker.exec(selector)) !== null ) { + parts.push( m[1] ); + + if ( m[2] ) { + extra = RegExp.rightContext; + break; + } + } + + if ( parts.length > 1 && origPOS.exec( selector ) ) { + if ( parts.length === 2 && Expr.relative[ parts[0] ] ) { + set = posProcess( parts[0] + parts[1], context ); + } else { + set = Expr.relative[ parts[0] ] ? + [ context ] : + Sizzle( parts.shift(), context ); + + while ( parts.length ) { + selector = parts.shift(); + + if ( Expr.relative[ selector ] ) + selector += parts.shift(); + + set = posProcess( selector, set ); + } + } + } else { + var ret = seed ? + { expr: parts.pop(), set: makeArray(seed) } : + Sizzle.find( parts.pop(), parts.length === 1 && context.parentNode ? context.parentNode : context, isXML(context) ); + set = Sizzle.filter( ret.expr, ret.set ); + + if ( parts.length > 0 ) { + checkSet = makeArray(set); + } else { + prune = false; + } + + while ( parts.length ) { + var cur = parts.pop(), pop = cur; + + if ( !Expr.relative[ cur ] ) { + cur = ""; + } else { + pop = parts.pop(); + } + + if ( pop == null ) { + pop = context; + } + + Expr.relative[ cur ]( checkSet, pop, isXML(context) ); + } + } + + if ( !checkSet ) { + checkSet = set; + } + + if ( !checkSet ) { + throw "Syntax error, unrecognized expression: " + (cur || selector); + } + + if ( toString.call(checkSet) === "[object Array]" ) { + if ( !prune ) { + results.push.apply( results, checkSet ); + } else if ( context.nodeType === 1 ) { + for ( var i = 0; checkSet[i] != null; i++ ) { + if ( checkSet[i] && (checkSet[i] === true || checkSet[i].nodeType === 1 && contains(context, checkSet[i])) ) { + results.push( set[i] ); + } + } + } else { + for ( var i = 0; checkSet[i] != null; i++ ) { + if ( checkSet[i] && checkSet[i].nodeType === 1 ) { + results.push( set[i] ); + } + } + } + } else { + makeArray( checkSet, results ); + } + + if ( extra ) { + Sizzle( extra, context, results, seed ); + + if ( sortOrder ) { + hasDuplicate = false; + results.sort(sortOrder); + + if ( hasDuplicate ) { + for ( var i = 1; i < results.length; i++ ) { + if ( results[i] === results[i-1] ) { + results.splice(i--, 1); + } + } + } + } + } + + return results; +}; + +Sizzle.matches = function(expr, set){ + return Sizzle(expr, null, null, set); +}; + +Sizzle.find = function(expr, context, isXML){ + var set, match; + + if ( !expr ) { + return []; + } + + for ( var i = 0, l = Expr.order.length; i < l; i++ ) { + var type = Expr.order[i], match; + + if ( (match = Expr.match[ type ].exec( expr )) ) { + var left = RegExp.leftContext; + + if ( left.substr( left.length - 1 ) !== "\\" ) { + match[1] = (match[1] || "").replace(/\\/g, ""); + set = Expr.find[ type ]( match, context, isXML ); + if ( set != null ) { + expr = expr.replace( Expr.match[ type ], "" ); + break; + } + } + } + } + + if ( !set ) { + set = context.getElementsByTagName("*"); + } + + return {set: set, expr: expr}; +}; + +Sizzle.filter = function(expr, set, inplace, not){ + var old = expr, result = [], curLoop = set, match, anyFound, + isXMLFilter = set && set[0] && isXML(set[0]); + + while ( expr && set.length ) { + for ( var type in Expr.filter ) { + if ( (match = Expr.match[ type ].exec( expr )) != null ) { + var filter = Expr.filter[ type ], found, item; + anyFound = false; + + if ( curLoop == result ) { + result = []; + } + + if ( Expr.preFilter[ type ] ) { + match = Expr.preFilter[ type ]( match, curLoop, inplace, result, not, isXMLFilter ); + + if ( !match ) { + anyFound = found = true; + } else if ( match === true ) { + continue; + } + } + + if ( match ) { + for ( var i = 0; (item = curLoop[i]) != null; i++ ) { + if ( item ) { + found = filter( item, match, i, curLoop ); + var pass = not ^ !!found; + + if ( inplace && found != null ) { + if ( pass ) { + anyFound = true; + } else { + curLoop[i] = false; + } + } else if ( pass ) { + result.push( item ); + anyFound = true; + } + } + } + } + + if ( found !== undefined ) { + if ( !inplace ) { + curLoop = result; + } + + expr = expr.replace( Expr.match[ type ], "" ); + + if ( !anyFound ) { + return []; + } + + break; + } + } + } + + // Improper expression + if ( expr == old ) { + if ( anyFound == null ) { + throw "Syntax error, unrecognized expression: " + expr; + } else { + break; + } + } + + old = expr; + } + + return curLoop; +}; + +var Expr = Sizzle.selectors = { + order: [ "ID", "NAME", "TAG" ], + match: { + ID: /#((?:[\w\u00c0-\uFFFF_-]|\\.)+)/, + CLASS: /\.((?:[\w\u00c0-\uFFFF_-]|\\.)+)/, + NAME: /\[name=['"]*((?:[\w\u00c0-\uFFFF_-]|\\.)+)['"]*\]/, + ATTR: /\[\s*((?:[\w\u00c0-\uFFFF_-]|\\.)+)\s*(?:(\S?=)\s*(['"]*)(.*?)\3|)\s*\]/, + TAG: /^((?:[\w\u00c0-\uFFFF\*_-]|\\.)+)/, + CHILD: /:(only|nth|last|first)-child(?:\((even|odd|[\dn+-]*)\))?/, + POS: /:(nth|eq|gt|lt|first|last|even|odd)(?:\((\d*)\))?(?=[^-]|$)/, + PSEUDO: /:((?:[\w\u00c0-\uFFFF_-]|\\.)+)(?:\((['"]*)((?:\([^\)]+\)|[^\2\(\)]*)+)\2\))?/ + }, + attrMap: { + "class": "className", + "for": "htmlFor" + }, + attrHandle: { + href: function(elem){ + return elem.getAttribute("href"); + } + }, + relative: { + "+": function(checkSet, part, isXML){ + var isPartStr = typeof part === "string", + isTag = isPartStr && !/\W/.test(part), + isPartStrNotTag = isPartStr && !isTag; + + if ( isTag && !isXML ) { + part = part.toUpperCase(); + } + + for ( var i = 0, l = checkSet.length, elem; i < l; i++ ) { + if ( (elem = checkSet[i]) ) { + while ( (elem = elem.previousSibling) && elem.nodeType !== 1 ) {} + + checkSet[i] = isPartStrNotTag || elem && elem.nodeName === part ? + elem || false : + elem === part; + } + } + + if ( isPartStrNotTag ) { + Sizzle.filter( part, checkSet, true ); + } + }, + ">": function(checkSet, part, isXML){ + var isPartStr = typeof part === "string"; + + if ( isPartStr && !/\W/.test(part) ) { + part = isXML ? part : part.toUpperCase(); + + for ( var i = 0, l = checkSet.length; i < l; i++ ) { + var elem = checkSet[i]; + if ( elem ) { + var parent = elem.parentNode; + checkSet[i] = parent.nodeName === part ? parent : false; + } + } + } else { + for ( var i = 0, l = checkSet.length; i < l; i++ ) { + var elem = checkSet[i]; + if ( elem ) { + checkSet[i] = isPartStr ? + elem.parentNode : + elem.parentNode === part; + } + } + + if ( isPartStr ) { + Sizzle.filter( part, checkSet, true ); + } + } + }, + "": function(checkSet, part, isXML){ + var doneName = done++, checkFn = dirCheck; + + if ( !part.match(/\W/) ) { + var nodeCheck = part = isXML ? part : part.toUpperCase(); + checkFn = dirNodeCheck; + } + + checkFn("parentNode", part, doneName, checkSet, nodeCheck, isXML); + }, + "~": function(checkSet, part, isXML){ + var doneName = done++, checkFn = dirCheck; + + if ( typeof part === "string" && !part.match(/\W/) ) { + var nodeCheck = part = isXML ? part : part.toUpperCase(); + checkFn = dirNodeCheck; + } + + checkFn("previousSibling", part, doneName, checkSet, nodeCheck, isXML); + } + }, + find: { + ID: function(match, context, isXML){ + if ( typeof context.getElementById !== "undefined" && !isXML ) { + var m = context.getElementById(match[1]); + return m ? [m] : []; + } + }, + NAME: function(match, context, isXML){ + if ( typeof context.getElementsByName !== "undefined" ) { + var ret = [], results = context.getElementsByName(match[1]); + + for ( var i = 0, l = results.length; i < l; i++ ) { + if ( results[i].getAttribute("name") === match[1] ) { + ret.push( results[i] ); + } + } + + return ret.length === 0 ? null : ret; + } + }, + TAG: function(match, context){ + return context.getElementsByTagName(match[1]); + } + }, + preFilter: { + CLASS: function(match, curLoop, inplace, result, not, isXML){ + match = " " + match[1].replace(/\\/g, "") + " "; + + if ( isXML ) { + return match; + } + + for ( var i = 0, elem; (elem = curLoop[i]) != null; i++ ) { + if ( elem ) { + if ( not ^ (elem.className && (" " + elem.className + " ").indexOf(match) >= 0) ) { + if ( !inplace ) + result.push( elem ); + } else if ( inplace ) { + curLoop[i] = false; + } + } + } + + return false; + }, + ID: function(match){ + return match[1].replace(/\\/g, ""); + }, + TAG: function(match, curLoop){ + for ( var i = 0; curLoop[i] === false; i++ ){} + return curLoop[i] && isXML(curLoop[i]) ? match[1] : match[1].toUpperCase(); + }, + CHILD: function(match){ + if ( match[1] == "nth" ) { + // parse equations like 'even', 'odd', '5', '2n', '3n+2', '4n-1', '-n+6' + var test = /(-?)(\d*)n((?:\+|-)?\d*)/.exec( + match[2] == "even" && "2n" || match[2] == "odd" && "2n+1" || + !/\D/.test( match[2] ) && "0n+" + match[2] || match[2]); + + // calculate the numbers (first)n+(last) including if they are negative + match[2] = (test[1] + (test[2] || 1)) - 0; + match[3] = test[3] - 0; + } + + // TODO: Move to normal caching system + match[0] = done++; + + return match; + }, + ATTR: function(match, curLoop, inplace, result, not, isXML){ + var name = match[1].replace(/\\/g, ""); + + if ( !isXML && Expr.attrMap[name] ) { + match[1] = Expr.attrMap[name]; + } + + if ( match[2] === "~=" ) { + match[4] = " " + match[4] + " "; + } + + return match; + }, + PSEUDO: function(match, curLoop, inplace, result, not){ + if ( match[1] === "not" ) { + // If we're dealing with a complex expression, or a simple one + if ( match[3].match(chunker).length > 1 || /^\w/.test(match[3]) ) { + match[3] = Sizzle(match[3], null, null, curLoop); + } else { + var ret = Sizzle.filter(match[3], curLoop, inplace, true ^ not); + if ( !inplace ) { + result.push.apply( result, ret ); + } + return false; + } + } else if ( Expr.match.POS.test( match[0] ) || Expr.match.CHILD.test( match[0] ) ) { + return true; + } + + return match; + }, + POS: function(match){ + match.unshift( true ); + return match; + } + }, + filters: { + enabled: function(elem){ + return elem.disabled === false && elem.type !== "hidden"; + }, + disabled: function(elem){ + return elem.disabled === true; + }, + checked: function(elem){ + return elem.checked === true; + }, + selected: function(elem){ + // Accessing this property makes selected-by-default + // options in Safari work properly + elem.parentNode.selectedIndex; + return elem.selected === true; + }, + parent: function(elem){ + return !!elem.firstChild; + }, + empty: function(elem){ + return !elem.firstChild; + }, + has: function(elem, i, match){ + return !!Sizzle( match[3], elem ).length; + }, + header: function(elem){ + return /h\d/i.test( elem.nodeName ); + }, + text: function(elem){ + return "text" === elem.type; + }, + radio: function(elem){ + return "radio" === elem.type; + }, + checkbox: function(elem){ + return "checkbox" === elem.type; + }, + file: function(elem){ + return "file" === elem.type; + }, + password: function(elem){ + return "password" === elem.type; + }, + submit: function(elem){ + return "submit" === elem.type; + }, + image: function(elem){ + return "image" === elem.type; + }, + reset: function(elem){ + return "reset" === elem.type; + }, + button: function(elem){ + return "button" === elem.type || elem.nodeName.toUpperCase() === "BUTTON"; + }, + input: function(elem){ + return /input|select|textarea|button/i.test(elem.nodeName); + } + }, + setFilters: { + first: function(elem, i){ + return i === 0; + }, + last: function(elem, i, match, array){ + return i === array.length - 1; + }, + even: function(elem, i){ + return i % 2 === 0; + }, + odd: function(elem, i){ + return i % 2 === 1; + }, + lt: function(elem, i, match){ + return i < match[3] - 0; + }, + gt: function(elem, i, match){ + return i > match[3] - 0; + }, + nth: function(elem, i, match){ + return match[3] - 0 == i; + }, + eq: function(elem, i, match){ + return match[3] - 0 == i; + } + }, + filter: { + PSEUDO: function(elem, match, i, array){ + var name = match[1], filter = Expr.filters[ name ]; + + if ( filter ) { + return filter( elem, i, match, array ); + } else if ( name === "contains" ) { + return (elem.textContent || elem.innerText || "").indexOf(match[3]) >= 0; + } else if ( name === "not" ) { + var not = match[3]; + + for ( var i = 0, l = not.length; i < l; i++ ) { + if ( not[i] === elem ) { + return false; + } + } + + return true; + } + }, + CHILD: function(elem, match){ + var type = match[1], node = elem; + switch (type) { + case 'only': + case 'first': + while (node = node.previousSibling) { + if ( node.nodeType === 1 ) return false; + } + if ( type == 'first') return true; + node = elem; + case 'last': + while (node = node.nextSibling) { + if ( node.nodeType === 1 ) return false; + } + return true; + case 'nth': + var first = match[2], last = match[3]; + + if ( first == 1 && last == 0 ) { + return true; + } + + var doneName = match[0], + parent = elem.parentNode; + + if ( parent && (parent.sizcache !== doneName || !elem.nodeIndex) ) { + var count = 0; + for ( node = parent.firstChild; node; node = node.nextSibling ) { + if ( node.nodeType === 1 ) { + node.nodeIndex = ++count; + } + } + parent.sizcache = doneName; + } + + var diff = elem.nodeIndex - last; + if ( first == 0 ) { + return diff == 0; + } else { + return ( diff % first == 0 && diff / first >= 0 ); + } + } + }, + ID: function(elem, match){ + return elem.nodeType === 1 && elem.getAttribute("id") === match; + }, + TAG: function(elem, match){ + return (match === "*" && elem.nodeType === 1) || elem.nodeName === match; + }, + CLASS: function(elem, match){ + return (" " + (elem.className || elem.getAttribute("class")) + " ") + .indexOf( match ) > -1; + }, + ATTR: function(elem, match){ + var name = match[1], + result = Expr.attrHandle[ name ] ? + Expr.attrHandle[ name ]( elem ) : + elem[ name ] != null ? + elem[ name ] : + elem.getAttribute( name ), + value = result + "", + type = match[2], + check = match[4]; + + return result == null ? + type === "!=" : + type === "=" ? + value === check : + type === "*=" ? + value.indexOf(check) >= 0 : + type === "~=" ? + (" " + value + " ").indexOf(check) >= 0 : + !check ? + value && result !== false : + type === "!=" ? + value != check : + type === "^=" ? + value.indexOf(check) === 0 : + type === "$=" ? + value.substr(value.length - check.length) === check : + type === "|=" ? + value === check || value.substr(0, check.length + 1) === check + "-" : + false; + }, + POS: function(elem, match, i, array){ + var name = match[2], filter = Expr.setFilters[ name ]; + + if ( filter ) { + return filter( elem, i, match, array ); + } + } + } +}; + +var origPOS = Expr.match.POS; + +for ( var type in Expr.match ) { + Expr.match[ type ] = RegExp( Expr.match[ type ].source + /(?![^\[]*\])(?![^\(]*\))/.source ); +} + +var makeArray = function(array, results) { + array = Array.prototype.slice.call( array ); + + if ( results ) { + results.push.apply( results, array ); + return results; + } + + return array; +}; + +// Perform a simple check to determine if the browser is capable of +// converting a NodeList to an array using builtin methods. +try { + Array.prototype.slice.call( document.documentElement.childNodes ); + +// Provide a fallback method if it does not work +} catch(e){ + makeArray = function(array, results) { + var ret = results || []; + + if ( toString.call(array) === "[object Array]" ) { + Array.prototype.push.apply( ret, array ); + } else { + if ( typeof array.length === "number" ) { + for ( var i = 0, l = array.length; i < l; i++ ) { + ret.push( array[i] ); + } + } else { + for ( var i = 0; array[i]; i++ ) { + ret.push( array[i] ); + } + } + } + + return ret; + }; +} + +var sortOrder; + +if ( document.documentElement.compareDocumentPosition ) { + sortOrder = function( a, b ) { + var ret = a.compareDocumentPosition(b) & 4 ? -1 : a === b ? 0 : 1; + if ( ret === 0 ) { + hasDuplicate = true; + } + return ret; + }; +} else if ( "sourceIndex" in document.documentElement ) { + sortOrder = function( a, b ) { + var ret = a.sourceIndex - b.sourceIndex; + if ( ret === 0 ) { + hasDuplicate = true; + } + return ret; + }; +} else if ( document.createRange ) { + sortOrder = function( a, b ) { + var aRange = a.ownerDocument.createRange(), bRange = b.ownerDocument.createRange(); + aRange.selectNode(a); + aRange.collapse(true); + bRange.selectNode(b); + bRange.collapse(true); + var ret = aRange.compareBoundaryPoints(Range.START_TO_END, bRange); + if ( ret === 0 ) { + hasDuplicate = true; + } + return ret; + }; +} + +// Check to see if the browser returns elements by name when +// querying by getElementById (and provide a workaround) +(function(){ + // We're going to inject a fake input element with a specified name + var form = document.createElement("form"), + id = "script" + (new Date).getTime(); + form.innerHTML = "<input name='" + id + "'/>"; + + // Inject it into the root element, check its status, and remove it quickly + var root = document.documentElement; + root.insertBefore( form, root.firstChild ); + + // The workaround has to do additional checks after a getElementById + // Which slows things down for other browsers (hence the branching) + if ( !!document.getElementById( id ) ) { + Expr.find.ID = function(match, context, isXML){ + if ( typeof context.getElementById !== "undefined" && !isXML ) { + var m = context.getElementById(match[1]); + return m ? m.id === match[1] || typeof m.getAttributeNode !== "undefined" && m.getAttributeNode("id").nodeValue === match[1] ? [m] : undefined : []; + } + }; + + Expr.filter.ID = function(elem, match){ + var node = typeof elem.getAttributeNode !== "undefined" && elem.getAttributeNode("id"); + return elem.nodeType === 1 && node && node.nodeValue === match; + }; + } + + root.removeChild( form ); +})(); + +(function(){ + // Check to see if the browser returns only elements + // when doing getElementsByTagName("*") + + // Create a fake element + var div = document.createElement("div"); + div.appendChild( document.createComment("") ); + + // Make sure no comments are found + if ( div.getElementsByTagName("*").length > 0 ) { + Expr.find.TAG = function(match, context){ + var results = context.getElementsByTagName(match[1]); + + // Filter out possible comments + if ( match[1] === "*" ) { + var tmp = []; + + for ( var i = 0; results[i]; i++ ) { + if ( results[i].nodeType === 1 ) { + tmp.push( results[i] ); + } + } + + results = tmp; + } + + return results; + }; + } + + // Check to see if an attribute returns normalized href attributes + div.innerHTML = "<a href='#'></a>"; + if ( div.firstChild && typeof div.firstChild.getAttribute !== "undefined" && + div.firstChild.getAttribute("href") !== "#" ) { + Expr.attrHandle.href = function(elem){ + return elem.getAttribute("href", 2); + }; + } +})(); + +if ( document.querySelectorAll ) (function(){ + var oldSizzle = Sizzle, div = document.createElement("div"); + div.innerHTML = "<p class='TEST'></p>"; + + // Safari can't handle uppercase or unicode characters when + // in quirks mode. + if ( div.querySelectorAll && div.querySelectorAll(".TEST").length === 0 ) { + return; + } + + Sizzle = function(query, context, extra, seed){ + context = context || document; + + // Only use querySelectorAll on non-XML documents + // (ID selectors don't work in non-HTML documents) + if ( !seed && context.nodeType === 9 && !isXML(context) ) { + try { + return makeArray( context.querySelectorAll(query), extra ); + } catch(e){} + } + + return oldSizzle(query, context, extra, seed); + }; + + Sizzle.find = oldSizzle.find; + Sizzle.filter = oldSizzle.filter; + Sizzle.selectors = oldSizzle.selectors; + Sizzle.matches = oldSizzle.matches; +})(); + +if ( document.getElementsByClassName && document.documentElement.getElementsByClassName ) (function(){ + var div = document.createElement("div"); + div.innerHTML = "<div class='test e'></div><div class='test'></div>"; + + // Opera can't find a second classname (in 9.6) + if ( div.getElementsByClassName("e").length === 0 ) + return; + + // Safari caches class attributes, doesn't catch changes (in 3.2) + div.lastChild.className = "e"; + + if ( div.getElementsByClassName("e").length === 1 ) + return; + + Expr.order.splice(1, 0, "CLASS"); + Expr.find.CLASS = function(match, context, isXML) { + if ( typeof context.getElementsByClassName !== "undefined" && !isXML ) { + return context.getElementsByClassName(match[1]); + } + }; +})(); + +function dirNodeCheck( dir, cur, doneName, checkSet, nodeCheck, isXML ) { + var sibDir = dir == "previousSibling" && !isXML; + for ( var i = 0, l = checkSet.length; i < l; i++ ) { + var elem = checkSet[i]; + if ( elem ) { + if ( sibDir && elem.nodeType === 1 ){ + elem.sizcache = doneName; + elem.sizset = i; + } + elem = elem[dir]; + var match = false; + + while ( elem ) { + if ( elem.sizcache === doneName ) { + match = checkSet[elem.sizset]; + break; + } + + if ( elem.nodeType === 1 && !isXML ){ + elem.sizcache = doneName; + elem.sizset = i; + } + + if ( elem.nodeName === cur ) { + match = elem; + break; + } + + elem = elem[dir]; + } + + checkSet[i] = match; + } + } +} + +function dirCheck( dir, cur, doneName, checkSet, nodeCheck, isXML ) { + var sibDir = dir == "previousSibling" && !isXML; + for ( var i = 0, l = checkSet.length; i < l; i++ ) { + var elem = checkSet[i]; + if ( elem ) { + if ( sibDir && elem.nodeType === 1 ) { + elem.sizcache = doneName; + elem.sizset = i; + } + elem = elem[dir]; + var match = false; + + while ( elem ) { + if ( elem.sizcache === doneName ) { + match = checkSet[elem.sizset]; + break; + } + + if ( elem.nodeType === 1 ) { + if ( !isXML ) { + elem.sizcache = doneName; + elem.sizset = i; + } + if ( typeof cur !== "string" ) { + if ( elem === cur ) { + match = true; + break; + } + + } else if ( Sizzle.filter( cur, [elem] ).length > 0 ) { + match = elem; + break; + } + } + + elem = elem[dir]; + } + + checkSet[i] = match; + } + } +} + +var contains = document.compareDocumentPosition ? function(a, b){ + return a.compareDocumentPosition(b) & 16; +} : function(a, b){ + return a !== b && (a.contains ? a.contains(b) : true); +}; + +var isXML = function(elem){ + return elem.nodeType === 9 && elem.documentElement.nodeName !== "HTML" || + !!elem.ownerDocument && isXML( elem.ownerDocument ); +}; + +var posProcess = function(selector, context){ + var tmpSet = [], later = "", match, + root = context.nodeType ? [context] : context; + + // Position selectors must be done after the filter + // And so must :not(positional) so we move all PSEUDOs to the end + while ( (match = Expr.match.PSEUDO.exec( selector )) ) { + later += match[0]; + selector = selector.replace( Expr.match.PSEUDO, "" ); + } + + selector = Expr.relative[selector] ? selector + "*" : selector; + + for ( var i = 0, l = root.length; i < l; i++ ) { + Sizzle( selector, root[i], tmpSet ); + } + + return Sizzle.filter( later, tmpSet ); +}; + +// EXPOSE +jQuery.find = Sizzle; +jQuery.filter = Sizzle.filter; +jQuery.expr = Sizzle.selectors; +jQuery.expr[":"] = jQuery.expr.filters; + +Sizzle.selectors.filters.hidden = function(elem){ + return elem.offsetWidth === 0 || elem.offsetHeight === 0; +}; + +Sizzle.selectors.filters.visible = function(elem){ + return elem.offsetWidth > 0 || elem.offsetHeight > 0; +}; + +Sizzle.selectors.filters.animated = function(elem){ + return jQuery.grep(jQuery.timers, function(fn){ + return elem === fn.elem; + }).length; +}; + +jQuery.multiFilter = function( expr, elems, not ) { + if ( not ) { + expr = ":not(" + expr + ")"; + } + + return Sizzle.matches(expr, elems); +}; + +jQuery.dir = function( elem, dir ){ + var matched = [], cur = elem[dir]; + while ( cur && cur != document ) { + if ( cur.nodeType == 1 ) + matched.push( cur ); + cur = cur[dir]; + } + return matched; +}; + +jQuery.nth = function(cur, result, dir, elem){ + result = result || 1; + var num = 0; + + for ( ; cur; cur = cur[dir] ) + if ( cur.nodeType == 1 && ++num == result ) + break; + + return cur; +}; + +jQuery.sibling = function(n, elem){ + var r = []; + + for ( ; n; n = n.nextSibling ) { + if ( n.nodeType == 1 && n != elem ) + r.push( n ); + } + + return r; +}; + +return; + +window.Sizzle = Sizzle; + +})(); +/* + * A number of helper functions used for managing events. + * Many of the ideas behind this code originated from + * Dean Edwards' addEvent library. + */ +jQuery.event = { + + // Bind an event to an element + // Original by Dean Edwards + add: function(elem, types, handler, data) { + if ( elem.nodeType == 3 || elem.nodeType == 8 ) + return; + + // For whatever reason, IE has trouble passing the window object + // around, causing it to be cloned in the process + if ( elem.setInterval && elem != window ) + elem = window; + + // Make sure that the function being executed has a unique ID + if ( !handler.guid ) + handler.guid = this.guid++; + + // if data is passed, bind to handler + if ( data !== undefined ) { + // Create temporary function pointer to original handler + var fn = handler; + + // Create unique handler function, wrapped around original handler + handler = this.proxy( fn ); + + // Store data in unique handler + handler.data = data; + } + + // Init the element's event structure + var events = jQuery.data(elem, "events") || jQuery.data(elem, "events", {}), + handle = jQuery.data(elem, "handle") || jQuery.data(elem, "handle", function(){ + // Handle the second event of a trigger and when + // an event is called after a page has unloaded + return typeof jQuery !== "undefined" && !jQuery.event.triggered ? + jQuery.event.handle.apply(arguments.callee.elem, arguments) : + undefined; + }); + // Add elem as a property of the handle function + // This is to prevent a memory leak with non-native + // event in IE. + handle.elem = elem; + + // Handle multiple events separated by a space + // jQuery(...).bind("mouseover mouseout", fn); + jQuery.each(types.split(/\s+/), function(index, type) { + // Namespaced event handlers + var namespaces = type.split("."); + type = namespaces.shift(); + handler.type = namespaces.slice().sort().join("."); + + // Get the current list of functions bound to this event + var handlers = events[type]; + + if ( jQuery.event.specialAll[type] ) + jQuery.event.specialAll[type].setup.call(elem, data, namespaces); + + // Init the event handler queue + if (!handlers) { + handlers = events[type] = {}; + + // Check for a special event handler + // Only use addEventListener/attachEvent if the special + // events handler returns false + if ( !jQuery.event.special[type] || jQuery.event.special[type].setup.call(elem, data, namespaces) === false ) { + // Bind the global event handler to the element + if (elem.addEventListener) + elem.addEventListener(type, handle, false); + else if (elem.attachEvent) + elem.attachEvent("on" + type, handle); + } + } + + // Add the function to the element's handler list + handlers[handler.guid] = handler; + + // Keep track of which events have been used, for global triggering + jQuery.event.global[type] = true; + }); + + // Nullify elem to prevent memory leaks in IE + elem = null; + }, + + guid: 1, + global: {}, + + // Detach an event or set of events from an element + remove: function(elem, types, handler) { + // don't do events on text and comment nodes + if ( elem.nodeType == 3 || elem.nodeType == 8 ) + return; + + var events = jQuery.data(elem, "events"), ret, index; + + if ( events ) { + // Unbind all events for the element + if ( types === undefined || (typeof types === "string" && types.charAt(0) == ".") ) + for ( var type in events ) + this.remove( elem, type + (types || "") ); + else { + // types is actually an event object here + if ( types.type ) { + handler = types.handler; + types = types.type; + } + + // Handle multiple events seperated by a space + // jQuery(...).unbind("mouseover mouseout", fn); + jQuery.each(types.split(/\s+/), function(index, type){ + // Namespaced event handlers + var namespaces = type.split("."); + type = namespaces.shift(); + var namespace = RegExp("(^|\\.)" + namespaces.slice().sort().join(".*\\.") + "(\\.|$)"); + + if ( events[type] ) { + // remove the given handler for the given type + if ( handler ) + delete events[type][handler.guid]; + + // remove all handlers for the given type + else + for ( var handle in events[type] ) + // Handle the removal of namespaced events + if ( namespace.test(events[type][handle].type) ) + delete events[type][handle]; + + if ( jQuery.event.specialAll[type] ) + jQuery.event.specialAll[type].teardown.call(elem, namespaces); + + // remove generic event handler if no more handlers exist + for ( ret in events[type] ) break; + if ( !ret ) { + if ( !jQuery.event.special[type] || jQuery.event.special[type].teardown.call(elem, namespaces) === false ) { + if (elem.removeEventListener) + elem.removeEventListener(type, jQuery.data(elem, "handle"), false); + else if (elem.detachEvent) + elem.detachEvent("on" + type, jQuery.data(elem, "handle")); + } + ret = null; + delete events[type]; + } + } + }); + } + + // Remove the expando if it's no longer used + for ( ret in events ) break; + if ( !ret ) { + var handle = jQuery.data( elem, "handle" ); + if ( handle ) handle.elem = null; + jQuery.removeData( elem, "events" ); + jQuery.removeData( elem, "handle" ); + } + } + }, + + // bubbling is internal + trigger: function( event, data, elem, bubbling ) { + // Event object or event type + var type = event.type || event; + + if( !bubbling ){ + event = typeof event === "object" ? + // jQuery.Event object + event[expando] ? event : + // Object literal + jQuery.extend( jQuery.Event(type), event ) : + // Just the event type (string) + jQuery.Event(type); + + if ( type.indexOf("!") >= 0 ) { + event.type = type = type.slice(0, -1); + event.exclusive = true; + } + + // Handle a global trigger + if ( !elem ) { + // Don't bubble custom events when global (to avoid too much overhead) + event.stopPropagation(); + // Only trigger if we've ever bound an event for it + if ( this.global[type] ) + jQuery.each( jQuery.cache, function(){ + if ( this.events && this.events[type] ) + jQuery.event.trigger( event, data, this.handle.elem ); + }); + } + + // Handle triggering a single element + + // don't do events on text and comment nodes + if ( !elem || elem.nodeType == 3 || elem.nodeType == 8 ) + return undefined; + + // Clean up in case it is reused + event.result = undefined; + event.target = elem; + + // Clone the incoming data, if any + data = jQuery.makeArray(data); + data.unshift( event ); + } + + event.currentTarget = elem; + + // Trigger the event, it is assumed that "handle" is a function + var handle = jQuery.data(elem, "handle"); + if ( handle ) + handle.apply( elem, data ); + + // Handle triggering native .onfoo handlers (and on links since we don't call .click() for links) + if ( (!elem[type] || (jQuery.nodeName(elem, 'a') && type == "click")) && elem["on"+type] && elem["on"+type].apply( elem, data ) === false ) + event.result = false; + + // Trigger the native events (except for clicks on links) + if ( !bubbling && elem[type] && !event.isDefaultPrevented() && !(jQuery.nodeName(elem, 'a') && type == "click") ) { + this.triggered = true; + try { + elem[ type ](); + // prevent IE from throwing an error for some hidden elements + } catch (e) {} + } + + this.triggered = false; + + if ( !event.isPropagationStopped() ) { + var parent = elem.parentNode || elem.ownerDocument; + if ( parent ) + jQuery.event.trigger(event, data, parent, true); + } + }, + + handle: function(event) { + // returned undefined or false + var all, handlers; + + event = arguments[0] = jQuery.event.fix( event || window.event ); + event.currentTarget = this; + + // Namespaced event handlers + var namespaces = event.type.split("."); + event.type = namespaces.shift(); + + // Cache this now, all = true means, any handler + all = !namespaces.length && !event.exclusive; + + var namespace = RegExp("(^|\\.)" + namespaces.slice().sort().join(".*\\.") + "(\\.|$)"); + + handlers = ( jQuery.data(this, "events") || {} )[event.type]; + + for ( var j in handlers ) { + var handler = handlers[j]; + + // Filter the functions by class + if ( all || namespace.test(handler.type) ) { + // Pass in a reference to the handler function itself + // So that we can later remove it + event.handler = handler; + event.data = handler.data; + + var ret = handler.apply(this, arguments); + + if( ret !== undefined ){ + event.result = ret; + if ( ret === false ) { + event.preventDefault(); + event.stopPropagation(); + } + } + + if( event.isImmediatePropagationStopped() ) + break; + + } + } + }, + + props: "altKey attrChange attrName bubbles button cancelable charCode clientX clientY ctrlKey currentTarget data detail eventPhase fromElement handler keyCode metaKey newValue originalTarget pageX pageY prevValue relatedNode relatedTarget screenX screenY shiftKey srcElement target toElement view wheelDelta which".split(" "), + + fix: function(event) { + if ( event[expando] ) + return event; + + // store a copy of the original event object + // and "clone" to set read-only properties + var originalEvent = event; + event = jQuery.Event( originalEvent ); + + for ( var i = this.props.length, prop; i; ){ + prop = this.props[ --i ]; + event[ prop ] = originalEvent[ prop ]; + } + + // Fix target property, if necessary + if ( !event.target ) + event.target = event.srcElement || document; // Fixes #1925 where srcElement might not be defined either + + // check if target is a textnode (safari) + if ( event.target.nodeType == 3 ) + event.target = event.target.parentNode; + + // Add relatedTarget, if necessary + if ( !event.relatedTarget && event.fromElement ) + event.relatedTarget = event.fromElement == event.target ? event.toElement : event.fromElement; + + // Calculate pageX/Y if missing and clientX/Y available + if ( event.pageX == null && event.clientX != null ) { + var doc = document.documentElement, body = document.body; + event.pageX = event.clientX + (doc && doc.scrollLeft || body && body.scrollLeft || 0) - (doc.clientLeft || 0); + event.pageY = event.clientY + (doc && doc.scrollTop || body && body.scrollTop || 0) - (doc.clientTop || 0); + } + + // Add which for key events + if ( !event.which && ((event.charCode || event.charCode === 0) ? event.charCode : event.keyCode) ) + event.which = event.charCode || event.keyCode; + + // Add metaKey to non-Mac browsers (use ctrl for PC's and Meta for Macs) + if ( !event.metaKey && event.ctrlKey ) + event.metaKey = event.ctrlKey; + + // Add which for click: 1 == left; 2 == middle; 3 == right + // Note: button is not normalized, so don't use it + if ( !event.which && event.button ) + event.which = (event.button & 1 ? 1 : ( event.button & 2 ? 3 : ( event.button & 4 ? 2 : 0 ) )); + + return event; + }, + + proxy: function( fn, proxy ){ + proxy = proxy || function(){ return fn.apply(this, arguments); }; + // Set the guid of unique handler to the same of original handler, so it can be removed + proxy.guid = fn.guid = fn.guid || proxy.guid || this.guid++; + // So proxy can be declared as an argument + return proxy; + }, + + special: { + ready: { + // Make sure the ready event is setup + setup: bindReady, + teardown: function() {} + } + }, + + specialAll: { + live: { + setup: function( selector, namespaces ){ + jQuery.event.add( this, namespaces[0], liveHandler ); + }, + teardown: function( namespaces ){ + if ( namespaces.length ) { + var remove = 0, name = RegExp("(^|\\.)" + namespaces[0] + "(\\.|$)"); + + jQuery.each( (jQuery.data(this, "events").live || {}), function(){ + if ( name.test(this.type) ) + remove++; + }); + + if ( remove < 1 ) + jQuery.event.remove( this, namespaces[0], liveHandler ); + } + } + } + } +}; + +jQuery.Event = function( src ){ + // Allow instantiation without the 'new' keyword + if( !this.preventDefault ) + return new jQuery.Event(src); + + // Event object + if( src && src.type ){ + this.originalEvent = src; + this.type = src.type; + // Event type + }else + this.type = src; + + // timeStamp is buggy for some events on Firefox(#3843) + // So we won't rely on the native value + this.timeStamp = now(); + + // Mark it as fixed + this[expando] = true; +}; + +function returnFalse(){ + return false; +} +function returnTrue(){ + return true; +} + +// jQuery.Event is based on DOM3 Events as specified by the ECMAScript Language Binding +// http://www.w3.org/TR/2003/WD-DOM-Level-3-Events-20030331/ecma-script-binding.html +jQuery.Event.prototype = { + preventDefault: function() { + this.isDefaultPrevented = returnTrue; + + var e = this.originalEvent; + if( !e ) + return; + // if preventDefault exists run it on the original event + if (e.preventDefault) + e.preventDefault(); + // otherwise set the returnValue property of the original event to false (IE) + e.returnValue = false; + }, + stopPropagation: function() { + this.isPropagationStopped = returnTrue; + + var e = this.originalEvent; + if( !e ) + return; + // if stopPropagation exists run it on the original event + if (e.stopPropagation) + e.stopPropagation(); + // otherwise set the cancelBubble property of the original event to true (IE) + e.cancelBubble = true; + }, + stopImmediatePropagation:function(){ + this.isImmediatePropagationStopped = returnTrue; + this.stopPropagation(); + }, + isDefaultPrevented: returnFalse, + isPropagationStopped: returnFalse, + isImmediatePropagationStopped: returnFalse +}; +// Checks if an event happened on an element within another element +// Used in jQuery.event.special.mouseenter and mouseleave handlers +var withinElement = function(event) { + // Check if mouse(over|out) are still within the same parent element + var parent = event.relatedTarget; + // Traverse up the tree + while ( parent && parent != this ) + try { parent = parent.parentNode; } + catch(e) { parent = this; } + + if( parent != this ){ + // set the correct event type + event.type = event.data; + // handle event if we actually just moused on to a non sub-element + jQuery.event.handle.apply( this, arguments ); + } +}; + +jQuery.each({ + mouseover: 'mouseenter', + mouseout: 'mouseleave' +}, function( orig, fix ){ + jQuery.event.special[ fix ] = { + setup: function(){ + jQuery.event.add( this, orig, withinElement, fix ); + }, + teardown: function(){ + jQuery.event.remove( this, orig, withinElement ); + } + }; +}); + +jQuery.fn.extend({ + bind: function( type, data, fn ) { + return type == "unload" ? this.one(type, data, fn) : this.each(function(){ + jQuery.event.add( this, type, fn || data, fn && data ); + }); + }, + + one: function( type, data, fn ) { + var one = jQuery.event.proxy( fn || data, function(event) { + jQuery(this).unbind(event, one); + return (fn || data).apply( this, arguments ); + }); + return this.each(function(){ + jQuery.event.add( this, type, one, fn && data); + }); + }, + + unbind: function( type, fn ) { + return this.each(function(){ + jQuery.event.remove( this, type, fn ); + }); + }, + + trigger: function( type, data ) { + return this.each(function(){ + jQuery.event.trigger( type, data, this ); + }); + }, + + triggerHandler: function( type, data ) { + if( this[0] ){ + var event = jQuery.Event(type); + event.preventDefault(); + event.stopPropagation(); + jQuery.event.trigger( event, data, this[0] ); + return event.result; + } + }, + + toggle: function( fn ) { + // Save reference to arguments for access in closure + var args = arguments, i = 1; + + // link all the functions, so any of them can unbind this click handler + while( i < args.length ) + jQuery.event.proxy( fn, args[i++] ); + + return this.click( jQuery.event.proxy( fn, function(event) { + // Figure out which function to execute + this.lastToggle = ( this.lastToggle || 0 ) % i; + + // Make sure that clicks stop + event.preventDefault(); + + // and execute the function + return args[ this.lastToggle++ ].apply( this, arguments ) || false; + })); + }, + + hover: function(fnOver, fnOut) { + return this.mouseenter(fnOver).mouseleave(fnOut); + }, + + ready: function(fn) { + // Attach the listeners + bindReady(); + + // If the DOM is already ready + if ( jQuery.isReady ) + // Execute the function immediately + fn.call( document, jQuery ); + + // Otherwise, remember the function for later + else + // Add the function to the wait list + jQuery.readyList.push( fn ); + + return this; + }, + + live: function( type, fn ){ + var proxy = jQuery.event.proxy( fn ); + proxy.guid += this.selector + type; + + jQuery(document).bind( liveConvert(type, this.selector), this.selector, proxy ); + + return this; + }, + + die: function( type, fn ){ + jQuery(document).unbind( liveConvert(type, this.selector), fn ? { guid: fn.guid + this.selector + type } : null ); + return this; + } +}); + +function liveHandler( event ){ + var check = RegExp("(^|\\.)" + event.type + "(\\.|$)"), + stop = true, + elems = []; + + jQuery.each(jQuery.data(this, "events").live || [], function(i, fn){ + if ( check.test(fn.type) ) { + var elem = jQuery(event.target).closest(fn.data)[0]; + if ( elem ) + elems.push({ elem: elem, fn: fn }); + } + }); + + elems.sort(function(a,b) { + return jQuery.data(a.elem, "closest") - jQuery.data(b.elem, "closest"); + }); + + jQuery.each(elems, function(){ + if ( this.fn.call(this.elem, event, this.fn.data) === false ) + return (stop = false); + }); + + return stop; +} + +function liveConvert(type, selector){ + return ["live", type, selector.replace(/\./g, "`").replace(/ /g, "|")].join("."); +} + +jQuery.extend({ + isReady: false, + readyList: [], + // Handle when the DOM is ready + ready: function() { + // Make sure that the DOM is not already loaded + if ( !jQuery.isReady ) { + // Remember that the DOM is ready + jQuery.isReady = true; + + // If there are functions bound, to execute + if ( jQuery.readyList ) { + // Execute all of them + jQuery.each( jQuery.readyList, function(){ + this.call( document, jQuery ); + }); + + // Reset the list of functions + jQuery.readyList = null; + } + + // Trigger any bound ready events + jQuery(document).triggerHandler("ready"); + } + } +}); + +var readyBound = false; + +function bindReady(){ + if ( readyBound ) return; + readyBound = true; + + // Mozilla, Opera and webkit nightlies currently support this event + if ( document.addEventListener ) { + // Use the handy event callback + document.addEventListener( "DOMContentLoaded", function(){ + document.removeEventListener( "DOMContentLoaded", arguments.callee, false ); + jQuery.ready(); + }, false ); + + // If IE event model is used + } else if ( document.attachEvent ) { + // ensure firing before onload, + // maybe late but safe also for iframes + document.attachEvent("onreadystatechange", function(){ + if ( document.readyState === "complete" ) { + document.detachEvent( "onreadystatechange", arguments.callee ); + jQuery.ready(); + } + }); + + // If IE and not an iframe + // continually check to see if the document is ready + if ( document.documentElement.doScroll && window == window.top ) (function(){ + if ( jQuery.isReady ) return; + + try { + // If IE is used, use the trick by Diego Perini + // http://javascript.nwbox.com/IEContentLoaded/ + document.documentElement.doScroll("left"); + } catch( error ) { + setTimeout( arguments.callee, 0 ); + return; + } + + // and execute any waiting functions + jQuery.ready(); + })(); + } + + // A fallback to window.onload, that will always work + jQuery.event.add( window, "load", jQuery.ready ); +} + +jQuery.each( ("blur,focus,load,resize,scroll,unload,click,dblclick," + + "mousedown,mouseup,mousemove,mouseover,mouseout,mouseenter,mouseleave," + + "change,select,submit,keydown,keypress,keyup,error").split(","), function(i, name){ + + // Handle event binding + jQuery.fn[name] = function(fn){ + return fn ? this.bind(name, fn) : this.trigger(name); + }; +}); + +// Prevent memory leaks in IE +// And prevent errors on refresh with events like mouseover in other browsers +// Window isn't included so as not to unbind existing unload events +jQuery( window ).bind( 'unload', function(){ + for ( var id in jQuery.cache ) + // Skip the window + if ( id != 1 && jQuery.cache[ id ].handle ) + jQuery.event.remove( jQuery.cache[ id ].handle.elem ); +}); +(function(){ + + jQuery.support = {}; + + var root = document.documentElement, + script = document.createElement("script"), + div = document.createElement("div"), + id = "script" + (new Date).getTime(); + + div.style.display = "none"; + div.innerHTML = ' <link/><table></table><a href="/a" style="color:red;float:left;opacity:.5;">a</a><select><option>text</option></select><object><param/></object>'; + + var all = div.getElementsByTagName("*"), + a = div.getElementsByTagName("a")[0]; + + // Can't get basic test support + if ( !all || !all.length || !a ) { + return; + } + + jQuery.support = { + // IE strips leading whitespace when .innerHTML is used + leadingWhitespace: div.firstChild.nodeType == 3, + + // Make sure that tbody elements aren't automatically inserted + // IE will insert them into empty tables + tbody: !div.getElementsByTagName("tbody").length, + + // Make sure that you can get all elements in an <object> element + // IE 7 always returns no results + objectAll: !!div.getElementsByTagName("object")[0] + .getElementsByTagName("*").length, + + // Make sure that link elements get serialized correctly by innerHTML + // This requires a wrapper element in IE + htmlSerialize: !!div.getElementsByTagName("link").length, + + // Get the style information from getAttribute + // (IE uses .cssText insted) + style: /red/.test( a.getAttribute("style") ), + + // Make sure that URLs aren't manipulated + // (IE normalizes it by default) + hrefNormalized: a.getAttribute("href") === "/a", + + // Make sure that element opacity exists + // (IE uses filter instead) + opacity: a.style.opacity === "0.5", + + // Verify style float existence + // (IE uses styleFloat instead of cssFloat) + cssFloat: !!a.style.cssFloat, + + // Will be defined later + scriptEval: false, + noCloneEvent: true, + boxModel: null + }; + + script.type = "text/javascript"; + try { + script.appendChild( document.createTextNode( "window." + id + "=1;" ) ); + } catch(e){} + + root.insertBefore( script, root.firstChild ); + + // Make sure that the execution of code works by injecting a script + // tag with appendChild/createTextNode + // (IE doesn't support this, fails, and uses .text instead) + if ( window[ id ] ) { + jQuery.support.scriptEval = true; + delete window[ id ]; + } + + root.removeChild( script ); + + if ( div.attachEvent && div.fireEvent ) { + div.attachEvent("onclick", function(){ + // Cloning a node shouldn't copy over any + // bound event handlers (IE does this) + jQuery.support.noCloneEvent = false; + div.detachEvent("onclick", arguments.callee); + }); + div.cloneNode(true).fireEvent("onclick"); + } + + // Figure out if the W3C box model works as expected + // document.body must exist before we can do this + jQuery(function(){ + var div = document.createElement("div"); + div.style.width = div.style.paddingLeft = "1px"; + + document.body.appendChild( div ); + jQuery.boxModel = jQuery.support.boxModel = div.offsetWidth === 2; + document.body.removeChild( div ).style.display = 'none'; + }); +})(); + +var styleFloat = jQuery.support.cssFloat ? "cssFloat" : "styleFloat"; + +jQuery.props = { + "for": "htmlFor", + "class": "className", + "float": styleFloat, + cssFloat: styleFloat, + styleFloat: styleFloat, + readonly: "readOnly", + maxlength: "maxLength", + cellspacing: "cellSpacing", + rowspan: "rowSpan", + tabindex: "tabIndex" +}; +jQuery.fn.extend({ + // Keep a copy of the old load + _load: jQuery.fn.load, + + load: function( url, params, callback ) { + if ( typeof url !== "string" ) + return this._load( url ); + + var off = url.indexOf(" "); + if ( off >= 0 ) { + var selector = url.slice(off, url.length); + url = url.slice(0, off); + } + + // Default to a GET request + var type = "GET"; + + // If the second parameter was provided + if ( params ) + // If it's a function + if ( jQuery.isFunction( params ) ) { + // We assume that it's the callback + callback = params; + params = null; + + // Otherwise, build a param string + } else if( typeof params === "object" ) { + params = jQuery.param( params ); + type = "POST"; + } + + var self = this; + + // Request the remote document + jQuery.ajax({ + url: url, + type: type, + dataType: "html", + data: params, + complete: function(res, status){ + // If successful, inject the HTML into all the matched elements + if ( status == "success" || status == "notmodified" ) + // See if a selector was specified + self.html( selector ? + // Create a dummy div to hold the results + jQuery("<div/>") + // inject the contents of the document in, removing the scripts + // to avoid any 'Permission Denied' errors in IE + .append(res.responseText.replace(/<script(.|\s)*?\/script>/g, "")) + + // Locate the specified elements + .find(selector) : + + // If not, just inject the full result + res.responseText ); + + if( callback ) + self.each( callback, [res.responseText, status, res] ); + } + }); + return this; + }, + + serialize: function() { + return jQuery.param(this.serializeArray()); + }, + serializeArray: function() { + return this.map(function(){ + return this.elements ? jQuery.makeArray(this.elements) : this; + }) + .filter(function(){ + return this.name && !this.disabled && + (this.checked || /select|textarea/i.test(this.nodeName) || + /text|hidden|password|search/i.test(this.type)); + }) + .map(function(i, elem){ + var val = jQuery(this).val(); + return val == null ? null : + jQuery.isArray(val) ? + jQuery.map( val, function(val, i){ + return {name: elem.name, value: val}; + }) : + {name: elem.name, value: val}; + }).get(); + } +}); + +// Attach a bunch of functions for handling common AJAX events +jQuery.each( "ajaxStart,ajaxStop,ajaxComplete,ajaxError,ajaxSuccess,ajaxSend".split(","), function(i,o){ + jQuery.fn[o] = function(f){ + return this.bind(o, f); + }; +}); + +var jsc = now(); + +jQuery.extend({ + + get: function( url, data, callback, type ) { + // shift arguments if data argument was ommited + if ( jQuery.isFunction( data ) ) { + callback = data; + data = null; + } + + return jQuery.ajax({ + type: "GET", + url: url, + data: data, + success: callback, + dataType: type + }); + }, + + getScript: function( url, callback ) { + return jQuery.get(url, null, callback, "script"); + }, + + getJSON: function( url, data, callback ) { + return jQuery.get(url, data, callback, "json"); + }, + + post: function( url, data, callback, type ) { + if ( jQuery.isFunction( data ) ) { + callback = data; + data = {}; + } + + return jQuery.ajax({ + type: "POST", + url: url, + data: data, + success: callback, + dataType: type + }); + }, + + ajaxSetup: function( settings ) { + jQuery.extend( jQuery.ajaxSettings, settings ); + }, + + ajaxSettings: { + url: location.href, + global: true, + type: "GET", + contentType: "application/x-www-form-urlencoded", + processData: true, + async: true, + /* + timeout: 0, + data: null, + username: null, + password: null, + */ + // Create the request object; Microsoft failed to properly + // implement the XMLHttpRequest in IE7, so we use the ActiveXObject when it is available + // This function can be overriden by calling jQuery.ajaxSetup + xhr:function(){ + return window.ActiveXObject ? new ActiveXObject("Microsoft.XMLHTTP") : new XMLHttpRequest(); + }, + accepts: { + xml: "application/xml, text/xml", + html: "text/html", + script: "text/javascript, application/javascript", + json: "application/json, text/javascript", + text: "text/plain", + _default: "*/*" + } + }, + + // Last-Modified header cache for next request + lastModified: {}, + + ajax: function( s ) { + // Extend the settings, but re-extend 's' so that it can be + // checked again later (in the test suite, specifically) + s = jQuery.extend(true, s, jQuery.extend(true, {}, jQuery.ajaxSettings, s)); + + var jsonp, jsre = /=\?(&|$)/g, status, data, + type = s.type.toUpperCase(); + + // convert data if not already a string + if ( s.data && s.processData && typeof s.data !== "string" ) + s.data = jQuery.param(s.data); + + // Handle JSONP Parameter Callbacks + if ( s.dataType == "jsonp" ) { + if ( type == "GET" ) { + if ( !s.url.match(jsre) ) + s.url += (s.url.match(/\?/) ? "&" : "?") + (s.jsonp || "callback") + "=?"; + } else if ( !s.data || !s.data.match(jsre) ) + s.data = (s.data ? s.data + "&" : "") + (s.jsonp || "callback") + "=?"; + s.dataType = "json"; + } + + // Build temporary JSONP function + if ( s.dataType == "json" && (s.data && s.data.match(jsre) || s.url.match(jsre)) ) { + jsonp = "jsonp" + jsc++; + + // Replace the =? sequence both in the query string and the data + if ( s.data ) + s.data = (s.data + "").replace(jsre, "=" + jsonp + "$1"); + s.url = s.url.replace(jsre, "=" + jsonp + "$1"); + + // We need to make sure + // that a JSONP style response is executed properly + s.dataType = "script"; + + // Handle JSONP-style loading + window[ jsonp ] = function(tmp){ + data = tmp; + success(); + complete(); + // Garbage collect + window[ jsonp ] = undefined; + try{ delete window[ jsonp ]; } catch(e){} + if ( head ) + head.removeChild( script ); + }; + } + + if ( s.dataType == "script" && s.cache == null ) + s.cache = false; + + if ( s.cache === false && type == "GET" ) { + var ts = now(); + // try replacing _= if it is there + var ret = s.url.replace(/(\?|&)_=.*?(&|$)/, "$1_=" + ts + "$2"); + // if nothing was replaced, add timestamp to the end + s.url = ret + ((ret == s.url) ? (s.url.match(/\?/) ? "&" : "?") + "_=" + ts : ""); + } + + // If data is available, append data to url for get requests + if ( s.data && type == "GET" ) { + s.url += (s.url.match(/\?/) ? "&" : "?") + s.data; + + // IE likes to send both get and post data, prevent this + s.data = null; + } + + // Watch for a new set of requests + if ( s.global && ! jQuery.active++ ) + jQuery.event.trigger( "ajaxStart" ); + + // Matches an absolute URL, and saves the domain + var parts = /^(\w+:)?\/\/([^\/?#]+)/.exec( s.url ); + + // If we're requesting a remote document + // and trying to load JSON or Script with a GET + if ( s.dataType == "script" && type == "GET" && parts + && ( parts[1] && parts[1] != location.protocol || parts[2] != location.host )){ + + var head = document.getElementsByTagName("head")[0]; + var script = document.createElement("script"); + script.src = s.url; + if (s.scriptCharset) + script.charset = s.scriptCharset; + + // Handle Script loading + if ( !jsonp ) { + var done = false; + + // Attach handlers for all browsers + script.onload = script.onreadystatechange = function(){ + if ( !done && (!this.readyState || + this.readyState == "loaded" || this.readyState == "complete") ) { + done = true; + success(); + complete(); + + // Handle memory leak in IE + script.onload = script.onreadystatechange = null; + head.removeChild( script ); + } + }; + } + + head.appendChild(script); + + // We handle everything using the script element injection + return undefined; + } + + var requestDone = false; + + // Create the request object + var xhr = s.xhr(); + + // Open the socket + // Passing null username, generates a login popup on Opera (#2865) + if( s.username ) + xhr.open(type, s.url, s.async, s.username, s.password); + else + xhr.open(type, s.url, s.async); + + // Need an extra try/catch for cross domain requests in Firefox 3 + try { + // Set the correct header, if data is being sent + if ( s.data ) + xhr.setRequestHeader("Content-Type", s.contentType); + + // Set the If-Modified-Since header, if ifModified mode. + if ( s.ifModified ) + xhr.setRequestHeader("If-Modified-Since", + jQuery.lastModified[s.url] || "Thu, 01 Jan 1970 00:00:00 GMT" ); + + // Set header so the called script knows that it's an XMLHttpRequest + xhr.setRequestHeader("X-Requested-With", "XMLHttpRequest"); + + // Set the Accepts header for the server, depending on the dataType + xhr.setRequestHeader("Accept", s.dataType && s.accepts[ s.dataType ] ? + s.accepts[ s.dataType ] + ", */*" : + s.accepts._default ); + } catch(e){} + + // Allow custom headers/mimetypes and early abort + if ( s.beforeSend && s.beforeSend(xhr, s) === false ) { + // Handle the global AJAX counter + if ( s.global && ! --jQuery.active ) + jQuery.event.trigger( "ajaxStop" ); + // close opended socket + xhr.abort(); + return false; + } + + if ( s.global ) + jQuery.event.trigger("ajaxSend", [xhr, s]); + + // Wait for a response to come back + var onreadystatechange = function(isTimeout){ + // The request was aborted, clear the interval and decrement jQuery.active + if (xhr.readyState == 0) { + if (ival) { + // clear poll interval + clearInterval(ival); + ival = null; + // Handle the global AJAX counter + if ( s.global && ! --jQuery.active ) + jQuery.event.trigger( "ajaxStop" ); + } + // The transfer is complete and the data is available, or the request timed out + } else if ( !requestDone && xhr && (xhr.readyState == 4 || isTimeout == "timeout") ) { + requestDone = true; + + // clear poll interval + if (ival) { + clearInterval(ival); + ival = null; + } + + status = isTimeout == "timeout" ? "timeout" : + !jQuery.httpSuccess( xhr ) ? "error" : + s.ifModified && jQuery.httpNotModified( xhr, s.url ) ? "notmodified" : + "success"; + + if ( status == "success" ) { + // Watch for, and catch, XML document parse errors + try { + // process the data (runs the xml through httpData regardless of callback) + data = jQuery.httpData( xhr, s.dataType, s ); + } catch(e) { + status = "parsererror"; + } + } + + // Make sure that the request was successful or notmodified + if ( status == "success" ) { + // Cache Last-Modified header, if ifModified mode. + var modRes; + try { + modRes = xhr.getResponseHeader("Last-Modified"); + } catch(e) {} // swallow exception thrown by FF if header is not available + + if ( s.ifModified && modRes ) + jQuery.lastModified[s.url] = modRes; + + // JSONP handles its own success callback + if ( !jsonp ) + success(); + } else + jQuery.handleError(s, xhr, status); + + // Fire the complete handlers + complete(); + + if ( isTimeout ) + xhr.abort(); + + // Stop memory leaks + if ( s.async ) + xhr = null; + } + }; + + if ( s.async ) { + // don't attach the handler to the request, just poll it instead + var ival = setInterval(onreadystatechange, 13); + + // Timeout checker + if ( s.timeout > 0 ) + setTimeout(function(){ + // Check to see if the request is still happening + if ( xhr && !requestDone ) + onreadystatechange( "timeout" ); + }, s.timeout); + } + + // Send the data + try { + xhr.send(s.data); + } catch(e) { + jQuery.handleError(s, xhr, null, e); + } + + // firefox 1.5 doesn't fire statechange for sync requests + if ( !s.async ) + onreadystatechange(); + + function success(){ + // If a local callback was specified, fire it and pass it the data + if ( s.success ) + s.success( data, status ); + + // Fire the global callback + if ( s.global ) + jQuery.event.trigger( "ajaxSuccess", [xhr, s] ); + } + + function complete(){ + // Process result + if ( s.complete ) + s.complete(xhr, status); + + // The request was completed + if ( s.global ) + jQuery.event.trigger( "ajaxComplete", [xhr, s] ); + + // Handle the global AJAX counter + if ( s.global && ! --jQuery.active ) + jQuery.event.trigger( "ajaxStop" ); + } + + // return XMLHttpRequest to allow aborting the request etc. + return xhr; + }, + + handleError: function( s, xhr, status, e ) { + // If a local callback was specified, fire it + if ( s.error ) s.error( xhr, status, e ); + + // Fire the global callback + if ( s.global ) + jQuery.event.trigger( "ajaxError", [xhr, s, e] ); + }, + + // Counter for holding the number of active queries + active: 0, + + // Determines if an XMLHttpRequest was successful or not + httpSuccess: function( xhr ) { + try { + // IE error sometimes returns 1223 when it should be 204 so treat it as success, see #1450 + return !xhr.status && location.protocol == "file:" || + ( xhr.status >= 200 && xhr.status < 300 ) || xhr.status == 304 || xhr.status == 1223; + } catch(e){} + return false; + }, + + // Determines if an XMLHttpRequest returns NotModified + httpNotModified: function( xhr, url ) { + try { + var xhrRes = xhr.getResponseHeader("Last-Modified"); + + // Firefox always returns 200. check Last-Modified date + return xhr.status == 304 || xhrRes == jQuery.lastModified[url]; + } catch(e){} + return false; + }, + + httpData: function( xhr, type, s ) { + var ct = xhr.getResponseHeader("content-type"), + xml = type == "xml" || !type && ct && ct.indexOf("xml") >= 0, + data = xml ? xhr.responseXML : xhr.responseText; + + if ( xml && data.documentElement.tagName == "parsererror" ) + throw "parsererror"; + + // Allow a pre-filtering function to sanitize the response + // s != null is checked to keep backwards compatibility + if( s && s.dataFilter ) + data = s.dataFilter( data, type ); + + // The filter can actually parse the response + if( typeof data === "string" ){ + + // If the type is "script", eval it in global context + if ( type == "script" ) + jQuery.globalEval( data ); + + // Get the JavaScript object, if JSON is used. + if ( type == "json" ) + data = window["eval"]("(" + data + ")"); + } + + return data; + }, + + // Serialize an array of form elements or a set of + // key/values into a query string + param: function( a ) { + var s = [ ]; + + function add( key, value ){ + s[ s.length ] = encodeURIComponent(key) + '=' + encodeURIComponent(value); + }; + + // If an array was passed in, assume that it is an array + // of form elements + if ( jQuery.isArray(a) || a.jquery ) + // Serialize the form elements + jQuery.each( a, function(){ + add( this.name, this.value ); + }); + + // Otherwise, assume that it's an object of key/value pairs + else + // Serialize the key/values + for ( var j in a ) + // If the value is an array then the key names need to be repeated + if ( jQuery.isArray(a[j]) ) + jQuery.each( a[j], function(){ + add( j, this ); + }); + else + add( j, jQuery.isFunction(a[j]) ? a[j]() : a[j] ); + + // Return the resulting serialization + return s.join("&").replace(/%20/g, "+"); + } + +}); +var elemdisplay = {}, + timerId, + fxAttrs = [ + // height animations + [ "height", "marginTop", "marginBottom", "paddingTop", "paddingBottom" ], + // width animations + [ "width", "marginLeft", "marginRight", "paddingLeft", "paddingRight" ], + // opacity animations + [ "opacity" ] + ]; + +function genFx( type, num ){ + var obj = {}; + jQuery.each( fxAttrs.concat.apply([], fxAttrs.slice(0,num)), function(){ + obj[ this ] = type; + }); + return obj; +} + +jQuery.fn.extend({ + show: function(speed,callback){ + if ( speed ) { + return this.animate( genFx("show", 3), speed, callback); + } else { + for ( var i = 0, l = this.length; i < l; i++ ){ + var old = jQuery.data(this[i], "olddisplay"); + + this[i].style.display = old || ""; + + if ( jQuery.css(this[i], "display") === "none" ) { + var tagName = this[i].tagName, display; + + if ( elemdisplay[ tagName ] ) { + display = elemdisplay[ tagName ]; + } else { + var elem = jQuery("<" + tagName + " />").appendTo("body"); + + display = elem.css("display"); + if ( display === "none" ) + display = "block"; + + elem.remove(); + + elemdisplay[ tagName ] = display; + } + + jQuery.data(this[i], "olddisplay", display); + } + } + + // Set the display of the elements in a second loop + // to avoid the constant reflow + for ( var i = 0, l = this.length; i < l; i++ ){ + this[i].style.display = jQuery.data(this[i], "olddisplay") || ""; + } + + return this; + } + }, + + hide: function(speed,callback){ + if ( speed ) { + return this.animate( genFx("hide", 3), speed, callback); + } else { + for ( var i = 0, l = this.length; i < l; i++ ){ + var old = jQuery.data(this[i], "olddisplay"); + if ( !old && old !== "none" ) + jQuery.data(this[i], "olddisplay", jQuery.css(this[i], "display")); + } + + // Set the display of the elements in a second loop + // to avoid the constant reflow + for ( var i = 0, l = this.length; i < l; i++ ){ + this[i].style.display = "none"; + } + + return this; + } + }, + + // Save the old toggle function + _toggle: jQuery.fn.toggle, + + toggle: function( fn, fn2 ){ + var bool = typeof fn === "boolean"; + + return jQuery.isFunction(fn) && jQuery.isFunction(fn2) ? + this._toggle.apply( this, arguments ) : + fn == null || bool ? + this.each(function(){ + var state = bool ? fn : jQuery(this).is(":hidden"); + jQuery(this)[ state ? "show" : "hide" ](); + }) : + this.animate(genFx("toggle", 3), fn, fn2); + }, + + fadeTo: function(speed,to,callback){ + return this.animate({opacity: to}, speed, callback); + }, + + animate: function( prop, speed, easing, callback ) { + var optall = jQuery.speed(speed, easing, callback); + + return this[ optall.queue === false ? "each" : "queue" ](function(){ + + var opt = jQuery.extend({}, optall), p, + hidden = this.nodeType == 1 && jQuery(this).is(":hidden"), + self = this; + + for ( p in prop ) { + if ( prop[p] == "hide" && hidden || prop[p] == "show" && !hidden ) + return opt.complete.call(this); + + if ( ( p == "height" || p == "width" ) && this.style ) { + // Store display property + opt.display = jQuery.css(this, "display"); + + // Make sure that nothing sneaks out + opt.overflow = this.style.overflow; + } + } + + if ( opt.overflow != null ) + this.style.overflow = "hidden"; + + opt.curAnim = jQuery.extend({}, prop); + + jQuery.each( prop, function(name, val){ + var e = new jQuery.fx( self, opt, name ); + + if ( /toggle|show|hide/.test(val) ) + e[ val == "toggle" ? hidden ? "show" : "hide" : val ]( prop ); + else { + var parts = val.toString().match(/^([+-]=)?([\d+-.]+)(.*)$/), + start = e.cur(true) || 0; + + if ( parts ) { + var end = parseFloat(parts[2]), + unit = parts[3] || "px"; + + // We need to compute starting value + if ( unit != "px" ) { + self.style[ name ] = (end || 1) + unit; + start = ((end || 1) / e.cur(true)) * start; + self.style[ name ] = start + unit; + } + + // If a +=/-= token was provided, we're doing a relative animation + if ( parts[1] ) + end = ((parts[1] == "-=" ? -1 : 1) * end) + start; + + e.custom( start, end, unit ); + } else + e.custom( start, val, "" ); + } + }); + + // For JS strict compliance + return true; + }); + }, + + stop: function(clearQueue, gotoEnd){ + var timers = jQuery.timers; + + if (clearQueue) + this.queue([]); + + this.each(function(){ + // go in reverse order so anything added to the queue during the loop is ignored + for ( var i = timers.length - 1; i >= 0; i-- ) + if ( timers[i].elem == this ) { + if (gotoEnd) + // force the next step to be the last + timers[i](true); + timers.splice(i, 1); + } + }); + + // start the next in the queue if the last step wasn't forced + if (!gotoEnd) + this.dequeue(); + + return this; + } + +}); + +// Generate shortcuts for custom animations +jQuery.each({ + slideDown: genFx("show", 1), + slideUp: genFx("hide", 1), + slideToggle: genFx("toggle", 1), + fadeIn: { opacity: "show" }, + fadeOut: { opacity: "hide" } +}, function( name, props ){ + jQuery.fn[ name ] = function( speed, callback ){ + return this.animate( props, speed, callback ); + }; +}); + +jQuery.extend({ + + speed: function(speed, easing, fn) { + var opt = typeof speed === "object" ? speed : { + complete: fn || !fn && easing || + jQuery.isFunction( speed ) && speed, + duration: speed, + easing: fn && easing || easing && !jQuery.isFunction(easing) && easing + }; + + opt.duration = jQuery.fx.off ? 0 : typeof opt.duration === "number" ? opt.duration : + jQuery.fx.speeds[opt.duration] || jQuery.fx.speeds._default; + + // Queueing + opt.old = opt.complete; + opt.complete = function(){ + if ( opt.queue !== false ) + jQuery(this).dequeue(); + if ( jQuery.isFunction( opt.old ) ) + opt.old.call( this ); + }; + + return opt; + }, + + easing: { + linear: function( p, n, firstNum, diff ) { + return firstNum + diff * p; + }, + swing: function( p, n, firstNum, diff ) { + return ((-Math.cos(p*Math.PI)/2) + 0.5) * diff + firstNum; + } + }, + + timers: [], + + fx: function( elem, options, prop ){ + this.options = options; + this.elem = elem; + this.prop = prop; + + if ( !options.orig ) + options.orig = {}; + } + +}); + +jQuery.fx.prototype = { + + // Simple function for setting a style value + update: function(){ + if ( this.options.step ) + this.options.step.call( this.elem, this.now, this ); + + (jQuery.fx.step[this.prop] || jQuery.fx.step._default)( this ); + + // Set display property to block for height/width animations + if ( ( this.prop == "height" || this.prop == "width" ) && this.elem.style ) + this.elem.style.display = "block"; + }, + + // Get the current size + cur: function(force){ + if ( this.elem[this.prop] != null && (!this.elem.style || this.elem.style[this.prop] == null) ) + return this.elem[ this.prop ]; + + var r = parseFloat(jQuery.css(this.elem, this.prop, force)); + return r && r > -10000 ? r : parseFloat(jQuery.curCSS(this.elem, this.prop)) || 0; + }, + + // Start an animation from one number to another + custom: function(from, to, unit){ + this.startTime = now(); + this.start = from; + this.end = to; + this.unit = unit || this.unit || "px"; + this.now = this.start; + this.pos = this.state = 0; + + var self = this; + function t(gotoEnd){ + return self.step(gotoEnd); + } + + t.elem = this.elem; + + if ( t() && jQuery.timers.push(t) && !timerId ) { + timerId = setInterval(function(){ + var timers = jQuery.timers; + + for ( var i = 0; i < timers.length; i++ ) + if ( !timers[i]() ) + timers.splice(i--, 1); + + if ( !timers.length ) { + clearInterval( timerId ); + timerId = undefined; + } + }, 13); + } + }, + + // Simple 'show' function + show: function(){ + // Remember where we started, so that we can go back to it later + this.options.orig[this.prop] = jQuery.attr( this.elem.style, this.prop ); + this.options.show = true; + + // Begin the animation + // Make sure that we start at a small width/height to avoid any + // flash of content + this.custom(this.prop == "width" || this.prop == "height" ? 1 : 0, this.cur()); + + // Start by showing the element + jQuery(this.elem).show(); + }, + + // Simple 'hide' function + hide: function(){ + // Remember where we started, so that we can go back to it later + this.options.orig[this.prop] = jQuery.attr( this.elem.style, this.prop ); + this.options.hide = true; + + // Begin the animation + this.custom(this.cur(), 0); + }, + + // Each step of an animation + step: function(gotoEnd){ + var t = now(); + + if ( gotoEnd || t >= this.options.duration + this.startTime ) { + this.now = this.end; + this.pos = this.state = 1; + this.update(); + + this.options.curAnim[ this.prop ] = true; + + var done = true; + for ( var i in this.options.curAnim ) + if ( this.options.curAnim[i] !== true ) + done = false; + + if ( done ) { + if ( this.options.display != null ) { + // Reset the overflow + this.elem.style.overflow = this.options.overflow; + + // Reset the display + this.elem.style.display = this.options.display; + if ( jQuery.css(this.elem, "display") == "none" ) + this.elem.style.display = "block"; + } + + // Hide the element if the "hide" operation was done + if ( this.options.hide ) + jQuery(this.elem).hide(); + + // Reset the properties, if the item has been hidden or shown + if ( this.options.hide || this.options.show ) + for ( var p in this.options.curAnim ) + jQuery.attr(this.elem.style, p, this.options.orig[p]); + + // Execute the complete function + this.options.complete.call( this.elem ); + } + + return false; + } else { + var n = t - this.startTime; + this.state = n / this.options.duration; + + // Perform the easing function, defaults to swing + this.pos = jQuery.easing[this.options.easing || (jQuery.easing.swing ? "swing" : "linear")](this.state, n, 0, 1, this.options.duration); + this.now = this.start + ((this.end - this.start) * this.pos); + + // Perform the next step of the animation + this.update(); + } + + return true; + } + +}; + +jQuery.extend( jQuery.fx, { + speeds:{ + slow: 600, + fast: 200, + // Default speed + _default: 400 + }, + step: { + + opacity: function(fx){ + jQuery.attr(fx.elem.style, "opacity", fx.now); + }, + + _default: function(fx){ + if ( fx.elem.style && fx.elem.style[ fx.prop ] != null ) + fx.elem.style[ fx.prop ] = fx.now + fx.unit; + else + fx.elem[ fx.prop ] = fx.now; + } + } +}); +if ( document.documentElement["getBoundingClientRect"] ) + jQuery.fn.offset = function() { + if ( !this[0] ) return { top: 0, left: 0 }; + if ( this[0] === this[0].ownerDocument.body ) return jQuery.offset.bodyOffset( this[0] ); + var box = this[0].getBoundingClientRect(), doc = this[0].ownerDocument, body = doc.body, docElem = doc.documentElement, + clientTop = docElem.clientTop || body.clientTop || 0, clientLeft = docElem.clientLeft || body.clientLeft || 0, + top = box.top + (self.pageYOffset || jQuery.boxModel && docElem.scrollTop || body.scrollTop ) - clientTop, + left = box.left + (self.pageXOffset || jQuery.boxModel && docElem.scrollLeft || body.scrollLeft) - clientLeft; + return { top: top, left: left }; + }; +else + jQuery.fn.offset = function() { + if ( !this[0] ) return { top: 0, left: 0 }; + if ( this[0] === this[0].ownerDocument.body ) return jQuery.offset.bodyOffset( this[0] ); + jQuery.offset.initialized || jQuery.offset.initialize(); + + var elem = this[0], offsetParent = elem.offsetParent, prevOffsetParent = elem, + doc = elem.ownerDocument, computedStyle, docElem = doc.documentElement, + body = doc.body, defaultView = doc.defaultView, + prevComputedStyle = defaultView.getComputedStyle(elem, null), + top = elem.offsetTop, left = elem.offsetLeft; + + while ( (elem = elem.parentNode) && elem !== body && elem !== docElem ) { + computedStyle = defaultView.getComputedStyle(elem, null); + top -= elem.scrollTop, left -= elem.scrollLeft; + if ( elem === offsetParent ) { + top += elem.offsetTop, left += elem.offsetLeft; + if ( jQuery.offset.doesNotAddBorder && !(jQuery.offset.doesAddBorderForTableAndCells && /^t(able|d|h)$/i.test(elem.tagName)) ) + top += parseInt( computedStyle.borderTopWidth, 10) || 0, + left += parseInt( computedStyle.borderLeftWidth, 10) || 0; + prevOffsetParent = offsetParent, offsetParent = elem.offsetParent; + } + if ( jQuery.offset.subtractsBorderForOverflowNotVisible && computedStyle.overflow !== "visible" ) + top += parseInt( computedStyle.borderTopWidth, 10) || 0, + left += parseInt( computedStyle.borderLeftWidth, 10) || 0; + prevComputedStyle = computedStyle; + } + + if ( prevComputedStyle.position === "relative" || prevComputedStyle.position === "static" ) + top += body.offsetTop, + left += body.offsetLeft; + + if ( prevComputedStyle.position === "fixed" ) + top += Math.max(docElem.scrollTop, body.scrollTop), + left += Math.max(docElem.scrollLeft, body.scrollLeft); + + return { top: top, left: left }; + }; + +jQuery.offset = { + initialize: function() { + if ( this.initialized ) return; + var body = document.body, container = document.createElement('div'), innerDiv, checkDiv, table, td, rules, prop, bodyMarginTop = body.style.marginTop, + html = '<div style="position:absolute;top:0;left:0;margin:0;border:5px solid #000;padding:0;width:1px;height:1px;"><div></div></div><table style="position:absolute;top:0;left:0;margin:0;border:5px solid #000;padding:0;width:1px;height:1px;" cellpadding="0" cellspacing="0"><tr><td></td></tr></table>'; + + rules = { position: 'absolute', top: 0, left: 0, margin: 0, border: 0, width: '1px', height: '1px', visibility: 'hidden' }; + for ( prop in rules ) container.style[prop] = rules[prop]; + + container.innerHTML = html; + body.insertBefore(container, body.firstChild); + innerDiv = container.firstChild, checkDiv = innerDiv.firstChild, td = innerDiv.nextSibling.firstChild.firstChild; + + this.doesNotAddBorder = (checkDiv.offsetTop !== 5); + this.doesAddBorderForTableAndCells = (td.offsetTop === 5); + + innerDiv.style.overflow = 'hidden', innerDiv.style.position = 'relative'; + this.subtractsBorderForOverflowNotVisible = (checkDiv.offsetTop === -5); + + body.style.marginTop = '1px'; + this.doesNotIncludeMarginInBodyOffset = (body.offsetTop === 0); + body.style.marginTop = bodyMarginTop; + + body.removeChild(container); + this.initialized = true; + }, + + bodyOffset: function(body) { + jQuery.offset.initialized || jQuery.offset.initialize(); + var top = body.offsetTop, left = body.offsetLeft; + if ( jQuery.offset.doesNotIncludeMarginInBodyOffset ) + top += parseInt( jQuery.curCSS(body, 'marginTop', true), 10 ) || 0, + left += parseInt( jQuery.curCSS(body, 'marginLeft', true), 10 ) || 0; + return { top: top, left: left }; + } +}; + + +jQuery.fn.extend({ + position: function() { + var left = 0, top = 0, results; + + if ( this[0] ) { + // Get *real* offsetParent + var offsetParent = this.offsetParent(), + + // Get correct offsets + offset = this.offset(), + parentOffset = /^body|html$/i.test(offsetParent[0].tagName) ? { top: 0, left: 0 } : offsetParent.offset(); + + // Subtract element margins + // note: when an element has margin: auto the offsetLeft and marginLeft + // are the same in Safari causing offset.left to incorrectly be 0 + offset.top -= num( this, 'marginTop' ); + offset.left -= num( this, 'marginLeft' ); + + // Add offsetParent borders + parentOffset.top += num( offsetParent, 'borderTopWidth' ); + parentOffset.left += num( offsetParent, 'borderLeftWidth' ); + + // Subtract the two offsets + results = { + top: offset.top - parentOffset.top, + left: offset.left - parentOffset.left + }; + } + + return results; + }, + + offsetParent: function() { + var offsetParent = this[0].offsetParent || document.body; + while ( offsetParent && (!/^body|html$/i.test(offsetParent.tagName) && jQuery.css(offsetParent, 'position') == 'static') ) + offsetParent = offsetParent.offsetParent; + return jQuery(offsetParent); + } +}); + + +// Create scrollLeft and scrollTop methods +jQuery.each( ['Left', 'Top'], function(i, name) { + var method = 'scroll' + name; + + jQuery.fn[ method ] = function(val) { + if (!this[0]) return null; + + return val !== undefined ? + + // Set the scroll offset + this.each(function() { + this == window || this == document ? + window.scrollTo( + !i ? val : jQuery(window).scrollLeft(), + i ? val : jQuery(window).scrollTop() + ) : + this[ method ] = val; + }) : + + // Return the scroll offset + this[0] == window || this[0] == document ? + self[ i ? 'pageYOffset' : 'pageXOffset' ] || + jQuery.boxModel && document.documentElement[ method ] || + document.body[ method ] : + this[0][ method ]; + }; +}); +// Create innerHeight, innerWidth, outerHeight and outerWidth methods +jQuery.each([ "Height", "Width" ], function(i, name){ + + var tl = i ? "Left" : "Top", // top or left + br = i ? "Right" : "Bottom", // bottom or right + lower = name.toLowerCase(); + + // innerHeight and innerWidth + jQuery.fn["inner" + name] = function(){ + return this[0] ? + jQuery.css( this[0], lower, false, "padding" ) : + null; + }; + + // outerHeight and outerWidth + jQuery.fn["outer" + name] = function(margin) { + return this[0] ? + jQuery.css( this[0], lower, false, margin ? "margin" : "border" ) : + null; + }; + + var type = name.toLowerCase(); + + jQuery.fn[ type ] = function( size ) { + // Get window width or height + return this[0] == window ? + // Everyone else use document.documentElement or document.body depending on Quirks vs Standards mode + document.compatMode == "CSS1Compat" && document.documentElement[ "client" + name ] || + document.body[ "client" + name ] : + + // Get document width or height + this[0] == document ? + // Either scroll[Width/Height] or offset[Width/Height], whichever is greater + Math.max( + document.documentElement["client" + name], + document.body["scroll" + name], document.documentElement["scroll" + name], + document.body["offset" + name], document.documentElement["offset" + name] + ) : + + // Get or set width or height on the element + size === undefined ? + // Get width or height on the element + (this.length ? jQuery.css( this[0], type ) : null) : + + // Set the width or height on the element (default to pixels if value is unitless) + this.css( type, typeof size === "string" ? size : size + "px" ); + }; + +}); +})(); diff --git a/doc/html/_static/minus.png b/doc/html/_static/minus.png Binary files differnew file mode 100644 index 0000000..da1c562 --- /dev/null +++ b/doc/html/_static/minus.png diff --git a/doc/html/_static/plus.png b/doc/html/_static/plus.png Binary files differnew file mode 100644 index 0000000..b3cb374 --- /dev/null +++ b/doc/html/_static/plus.png diff --git a/doc/html/_static/pygments.css b/doc/html/_static/pygments.css new file mode 100644 index 0000000..1f2d2b6 --- /dev/null +++ b/doc/html/_static/pygments.css @@ -0,0 +1,61 @@ +.hll { background-color: #ffffcc } +.c { color: #408090; font-style: italic } /* Comment */ +.err { border: 1px solid #FF0000 } /* Error */ +.k { color: #007020; font-weight: bold } /* Keyword */ +.o { color: #666666 } /* Operator */ +.cm { color: #408090; font-style: italic } /* Comment.Multiline */ +.cp { color: #007020 } /* Comment.Preproc */ +.c1 { color: #408090; font-style: italic } /* Comment.Single */ +.cs { color: #408090; background-color: #fff0f0 } /* Comment.Special */ +.gd { color: #A00000 } /* Generic.Deleted */ +.ge { font-style: italic } /* Generic.Emph */ +.gr { color: #FF0000 } /* Generic.Error */ +.gh { color: #000080; font-weight: bold } /* Generic.Heading */ +.gi { color: #00A000 } /* Generic.Inserted */ +.go { color: #303030 } /* Generic.Output */ +.gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */ +.gs { font-weight: bold } /* Generic.Strong */ +.gu { color: #800080; font-weight: bold } /* Generic.Subheading */ +.gt { color: #0040D0 } /* Generic.Traceback */ +.kc { color: #007020; font-weight: bold } /* Keyword.Constant */ +.kd { color: #007020; font-weight: bold } /* Keyword.Declaration */ +.kn { color: #007020; font-weight: bold } /* Keyword.Namespace */ +.kp { color: #007020 } /* Keyword.Pseudo */ +.kr { color: #007020; font-weight: bold } /* Keyword.Reserved */ +.kt { color: #902000 } /* Keyword.Type */ +.m { color: #208050 } /* Literal.Number */ +.s { color: #4070a0 } /* Literal.String */ +.na { color: #4070a0 } /* Name.Attribute */ +.nb { color: #007020 } /* Name.Builtin */ +.nc { color: #0e84b5; font-weight: bold } /* Name.Class */ +.no { color: #60add5 } /* Name.Constant */ +.nd { color: #555555; font-weight: bold } /* Name.Decorator */ +.ni { color: #d55537; font-weight: bold } /* Name.Entity */ +.ne { color: #007020 } /* Name.Exception */ +.nf { color: #06287e } /* Name.Function */ +.nl { color: #002070; font-weight: bold } /* Name.Label */ +.nn { color: #0e84b5; font-weight: bold } /* Name.Namespace */ +.nt { color: #062873; font-weight: bold } /* Name.Tag */ +.nv { color: #bb60d5 } /* Name.Variable */ +.ow { color: #007020; font-weight: bold } /* Operator.Word */ +.w { color: #bbbbbb } /* Text.Whitespace */ +.mf { color: #208050 } /* Literal.Number.Float */ +.mh { color: #208050 } /* Literal.Number.Hex */ +.mi { color: #208050 } /* Literal.Number.Integer */ +.mo { color: #208050 } /* Literal.Number.Oct */ +.sb { color: #4070a0 } /* Literal.String.Backtick */ +.sc { color: #4070a0 } /* Literal.String.Char */ +.sd { color: #4070a0; font-style: italic } /* Literal.String.Doc */ +.s2 { color: #4070a0 } /* Literal.String.Double */ +.se { color: #4070a0; font-weight: bold } /* Literal.String.Escape */ +.sh { color: #4070a0 } /* Literal.String.Heredoc */ +.si { color: #70a0d0; font-style: italic } /* Literal.String.Interpol */ +.sx { color: #c65d09 } /* Literal.String.Other */ +.sr { color: #235388 } /* Literal.String.Regex */ +.s1 { color: #4070a0 } /* Literal.String.Single */ +.ss { color: #517918 } /* Literal.String.Symbol */ +.bp { color: #007020 } /* Name.Builtin.Pseudo */ +.vc { color: #bb60d5 } /* Name.Variable.Class */ +.vg { color: #bb60d5 } /* Name.Variable.Global */ +.vi { color: #bb60d5 } /* Name.Variable.Instance */ +.il { color: #208050 } /* Literal.Number.Integer.Long */
\ No newline at end of file diff --git a/doc/html/_static/searchtools.js b/doc/html/_static/searchtools.js new file mode 100644 index 0000000..e022625 --- /dev/null +++ b/doc/html/_static/searchtools.js @@ -0,0 +1,467 @@ +/** + * helper function to return a node containing the + * search summary for a given text. keywords is a list + * of stemmed words, hlwords is the list of normal, unstemmed + * words. the first one is used to find the occurance, the + * latter for highlighting it. + */ + +jQuery.makeSearchSummary = function(text, keywords, hlwords) { + var textLower = text.toLowerCase(); + var start = 0; + $.each(keywords, function() { + var i = textLower.indexOf(this.toLowerCase()); + if (i > -1) + start = i; + }); + start = Math.max(start - 120, 0); + var excerpt = ((start > 0) ? '...' : '') + + $.trim(text.substr(start, 240)) + + ((start + 240 - text.length) ? '...' : ''); + var rv = $('<div class="context"></div>').text(excerpt); + $.each(hlwords, function() { + rv = rv.highlightText(this, 'highlight'); + }); + return rv; +} + +/** + * Porter Stemmer + */ +var PorterStemmer = function() { + + var step2list = { + ational: 'ate', + tional: 'tion', + enci: 'ence', + anci: 'ance', + izer: 'ize', + bli: 'ble', + alli: 'al', + entli: 'ent', + eli: 'e', + ousli: 'ous', + ization: 'ize', + ation: 'ate', + ator: 'ate', + alism: 'al', + iveness: 'ive', + fulness: 'ful', + ousness: 'ous', + aliti: 'al', + iviti: 'ive', + biliti: 'ble', + logi: 'log' + }; + + var step3list = { + icate: 'ic', + ative: '', + alize: 'al', + iciti: 'ic', + ical: 'ic', + ful: '', + ness: '' + }; + + var c = "[^aeiou]"; // consonant + var v = "[aeiouy]"; // vowel + var C = c + "[^aeiouy]*"; // consonant sequence + var V = v + "[aeiou]*"; // vowel sequence + + var mgr0 = "^(" + C + ")?" + V + C; // [C]VC... is m>0 + var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$"; // [C]VC[V] is m=1 + var mgr1 = "^(" + C + ")?" + V + C + V + C; // [C]VCVC... is m>1 + var s_v = "^(" + C + ")?" + v; // vowel in stem + + this.stemWord = function (w) { + var stem; + var suffix; + var firstch; + var origword = w; + + if (w.length < 3) + return w; + + var re; + var re2; + var re3; + var re4; + + firstch = w.substr(0,1); + if (firstch == "y") + w = firstch.toUpperCase() + w.substr(1); + + // Step 1a + re = /^(.+?)(ss|i)es$/; + re2 = /^(.+?)([^s])s$/; + + if (re.test(w)) + w = w.replace(re,"$1$2"); + else if (re2.test(w)) + w = w.replace(re2,"$1$2"); + + // Step 1b + re = /^(.+?)eed$/; + re2 = /^(.+?)(ed|ing)$/; + if (re.test(w)) { + var fp = re.exec(w); + re = new RegExp(mgr0); + if (re.test(fp[1])) { + re = /.$/; + w = w.replace(re,""); + } + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1]; + re2 = new RegExp(s_v); + if (re2.test(stem)) { + w = stem; + re2 = /(at|bl|iz)$/; + re3 = new RegExp("([^aeiouylsz])\\1$"); + re4 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re2.test(w)) + w = w + "e"; + else if (re3.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + else if (re4.test(w)) + w = w + "e"; + } + } + + // Step 1c + re = /^(.+?)y$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(s_v); + if (re.test(stem)) + w = stem + "i"; + } + + // Step 2 + re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step2list[suffix]; + } + + // Step 3 + re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step3list[suffix]; + } + + // Step 4 + re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/; + re2 = /^(.+?)(s|t)(ion)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + if (re.test(stem)) + w = stem; + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1] + fp[2]; + re2 = new RegExp(mgr1); + if (re2.test(stem)) + w = stem; + } + + // Step 5 + re = /^(.+?)e$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + re2 = new RegExp(meq1); + re3 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re.test(stem) || (re2.test(stem) && !(re3.test(stem)))) + w = stem; + } + re = /ll$/; + re2 = new RegExp(mgr1); + if (re.test(w) && re2.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + + // and turn initial Y back to y + if (firstch == "y") + w = firstch.toLowerCase() + w.substr(1); + return w; + } +} + + +/** + * Search Module + */ +var Search = { + + _index : null, + _queued_query : null, + _pulse_status : -1, + + init : function() { + var params = $.getQueryParameters(); + if (params.q) { + var query = params.q[0]; + $('input[name="q"]')[0].value = query; + this.performSearch(query); + } + }, + + /** + * Sets the index + */ + setIndex : function(index) { + var q; + this._index = index; + if ((q = this._queued_query) !== null) { + this._queued_query = null; + Search.query(q); + } + }, + + hasIndex : function() { + return this._index !== null; + }, + + deferQuery : function(query) { + this._queued_query = query; + }, + + stopPulse : function() { + this._pulse_status = 0; + }, + + startPulse : function() { + if (this._pulse_status >= 0) + return; + function pulse() { + Search._pulse_status = (Search._pulse_status + 1) % 4; + var dotString = ''; + for (var i = 0; i < Search._pulse_status; i++) + dotString += '.'; + Search.dots.text(dotString); + if (Search._pulse_status > -1) + window.setTimeout(pulse, 500); + }; + pulse(); + }, + + /** + * perform a search for something + */ + performSearch : function(query) { + // create the required interface elements + this.out = $('#search-results'); + this.title = $('<h2>' + _('Searching') + '</h2>').appendTo(this.out); + this.dots = $('<span></span>').appendTo(this.title); + this.status = $('<p style="display: none"></p>').appendTo(this.out); + this.output = $('<ul class="search"/>').appendTo(this.out); + + $('#search-progress').text(_('Preparing search...')); + this.startPulse(); + + // index already loaded, the browser was quick! + if (this.hasIndex()) + this.query(query); + else + this.deferQuery(query); + }, + + query : function(query) { + // stem the searchterms and add them to the + // correct list + var stemmer = new PorterStemmer(); + var searchterms = []; + var excluded = []; + var hlterms = []; + var tmp = query.split(/\s+/); + var object = (tmp.length == 1) ? tmp[0].toLowerCase() : null; + for (var i = 0; i < tmp.length; i++) { + // stem the word + var word = stemmer.stemWord(tmp[i]).toLowerCase(); + // select the correct list + if (word[0] == '-') { + var toAppend = excluded; + word = word.substr(1); + } + else { + var toAppend = searchterms; + hlterms.push(tmp[i].toLowerCase()); + } + // only add if not already in the list + if (!$.contains(toAppend, word)) + toAppend.push(word); + }; + var highlightstring = '?highlight=' + $.urlencode(hlterms.join(" ")); + + console.debug('SEARCH: searching for:'); + console.info('required: ', searchterms); + console.info('excluded: ', excluded); + + // prepare search + var filenames = this._index.filenames; + var titles = this._index.titles; + var terms = this._index.terms; + var descrefs = this._index.descrefs; + var modules = this._index.modules; + var desctypes = this._index.desctypes; + var fileMap = {}; + var files = null; + var objectResults = []; + var regularResults = []; + $('#search-progress').empty(); + + // lookup as object + if (object != null) { + for (var module in modules) { + if (module.indexOf(object) > -1) { + fn = modules[module]; + descr = _('module, in ') + titles[fn]; + objectResults.push([filenames[fn], module, '#module-'+module, descr]); + } + } + for (var prefix in descrefs) { + for (var name in descrefs[prefix]) { + var fullname = (prefix ? prefix + '.' : '') + name; + if (fullname.toLowerCase().indexOf(object) > -1) { + match = descrefs[prefix][name]; + descr = desctypes[match[1]] + _(', in ') + titles[match[0]]; + objectResults.push([filenames[match[0]], fullname, '#'+fullname, descr]); + } + } + } + } + + // sort results descending + objectResults.sort(function(a, b) { + return (a[1] > b[1]) ? -1 : ((a[1] < b[1]) ? 1 : 0); + }); + + + // perform the search on the required terms + for (var i = 0; i < searchterms.length; i++) { + var word = searchterms[i]; + // no match but word was a required one + if ((files = terms[word]) == null) + break; + if (files.length == undefined) { + files = [files]; + } + // create the mapping + for (var j = 0; j < files.length; j++) { + var file = files[j]; + if (file in fileMap) + fileMap[file].push(word); + else + fileMap[file] = [word]; + } + } + + // now check if the files don't contain excluded terms + for (var file in fileMap) { + var valid = true; + + // check if all requirements are matched + if (fileMap[file].length != searchterms.length) + continue; + + // ensure that none of the excluded terms is in the + // search result. + for (var i = 0; i < excluded.length; i++) { + if (terms[excluded[i]] == file || + $.contains(terms[excluded[i]] || [], file)) { + valid = false; + break; + } + } + + // if we have still a valid result we can add it + // to the result list + if (valid) + regularResults.push([filenames[file], titles[file], '', null]); + } + + // delete unused variables in order to not waste + // memory until list is retrieved completely + delete filenames, titles, terms; + + // now sort the regular results descending by title + regularResults.sort(function(a, b) { + var left = a[1].toLowerCase(); + var right = b[1].toLowerCase(); + return (left > right) ? -1 : ((left < right) ? 1 : 0); + }); + + // combine both + var results = regularResults.concat(objectResults); + + // print the results + var resultCount = results.length; + function displayNextItem() { + // results left, load the summary and display it + if (results.length) { + var item = results.pop(); + var listItem = $('<li style="display:none"></li>'); + listItem.append($('<a/>').attr( + 'href', + item[0] + DOCUMENTATION_OPTIONS.FILE_SUFFIX + + highlightstring + item[2]).html(item[1])); + if (item[3]) { + listItem.append($('<span> (' + item[3] + ')</span>')); + Search.output.append(listItem); + listItem.slideDown(5, function() { + displayNextItem(); + }); + } else if (DOCUMENTATION_OPTIONS.HAS_SOURCE) { + $.get('_sources/' + item[0] + '.txt', function(data) { + listItem.append($.makeSearchSummary(data, searchterms, hlterms)); + Search.output.append(listItem); + listItem.slideDown(5, function() { + displayNextItem(); + }); + }); + } else { + // no source available, just display title + Search.output.append(listItem); + listItem.slideDown(5, function() { + displayNextItem(); + }); + } + } + // search finished, update title and status message + else { + Search.stopPulse(); + Search.title.text(_('Search Results')); + if (!resultCount) + Search.status.text(_('Your search did not match any documents. Please make sure that all words are spelled correctly and that you\'ve selected enough categories.')); + else + Search.status.text(_('Search finished, found %s page(s) matching the search query.').replace('%s', resultCount)); + Search.status.fadeIn(500); + } + } + displayNextItem(); + } +} + +$(document).ready(function() { + Search.init(); +}); diff --git a/doc/html/annotations.html b/doc/html/annotations.html new file mode 100644 index 0000000..fc76524 --- /dev/null +++ b/doc/html/annotations.html @@ -0,0 +1,901 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + + <title>Annotations — SIP 4.10.5 Reference Guide</title> + <link rel="stylesheet" href="_static/default.css" type="text/css" /> + <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '#', + VERSION: '4.10.5', + COLLAPSE_MODINDEX: false, + FILE_SUFFIX: '.html', + HAS_SOURCE: true + }; + </script> + <script type="text/javascript" src="_static/jquery.js"></script> + <script type="text/javascript" src="_static/doctools.js"></script> + <link rel="top" title="SIP 4.10.5 Reference Guide" href="index.html" /> + <link rel="next" title="C API for Handwritten Code" href="c_api.html" /> + <link rel="prev" title="Directives" href="directives.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="modindex.html" title="Global Module Index" + accesskey="M">modules</a> |</li> + <li class="right" > + <a href="c_api.html" title="C API for Handwritten Code" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="directives.html" title="Directives" + accesskey="P">previous</a> |</li> + <li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="annotations"> +<h1>Annotations<a class="headerlink" href="#annotations" title="Permalink to this headline">¶</a></h1> +<p>In this section we describe each of the annotations that can be used in +specification files.</p> +<p>Annotations can either be <a class="reference internal" href="#ref-arg-annos"><em>argument annotations</em></a>, +<a class="reference internal" href="#ref-class-annos"><em>class annotations</em></a>, <a class="reference internal" href="#ref-mapped-type-annos"><em>mapped type annotations</em></a>, <a class="reference internal" href="#ref-enum-annos"><em>enum annotations</em></a>, +<a class="reference internal" href="#ref-exception-annos"><em>exception annotations</em></a>, <a class="reference internal" href="#ref-function-annos"><em>function annotations</em></a>, <a class="reference internal" href="#ref-license-annos"><em>license annotations</em></a>, +<a class="reference internal" href="#ref-typedef-annos"><em>typedef annotations</em></a> or <a class="reference internal" href="#ref-variable-annos"><em>variable annotations</em></a> depending on the context in which they can be used.</p> +<p>Annotations are placed between forward slashes (<tt class="docutils literal"><span class="pre">/</span></tt>). Multiple annotations +are comma separated within the slashes.</p> +<p>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 +<tt class="docutils literal"><span class="pre">=</span></tt>.</p> +<p>Annotations can have one of the following types:</p> +<dl class="docutils"> +<dt><em>boolean</em></dt> +<dd>This type of annotation has no value and is implicitly true.</dd> +<dt><em>name</em></dt> +<dd>The value is a name that is compatible with a C/C++ identifier. In some +cases the value is optional.</dd> +<dt><em>dotted name</em></dt> +<dd>The value is a name that is compatible with an identifier preceded by a +Python scope.</dd> +<dt><em>string</em></dt> +<dd>The value is a double quoted string.</dd> +<dt><em>API range</em></dt> +<dd><p class="first">The value is the name of an API (defined using the <a class="reference external" href="directives.html#directive-%API"><tt class="xref docutils literal"><span class="pre">%API</span></tt></a> +directive) separated by a range of version numbers with a colon.</p> +<p>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.</p> +<p>For example:</p> +<div class="last highlight-python"><pre># 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-/</pre> +</div> +</dd> +</dl> +<p>The following example shows argument and function annotations:</p> +<div class="highlight-python"><pre>void exec(QWidget * /Transfer/) /ReleaseGIL, PyName=call_exec/;</pre> +</div> +<p>Note that the current version of SIP does not complain about unknown +annotations, or annotations used out of their correct context.</p> +<div class="section" id="argument-annotations"> +<span id="ref-arg-annos"></span><h2>Argument Annotations<a class="headerlink" href="#argument-annotations" title="Permalink to this headline">¶</a></h2> +<dl class="argument-annotation"> +<dt id="aanno-AllowNone"> +<tt class="descname">AllowNone</tt><a class="headerlink" href="#aanno-AllowNone" title="Permalink to this definition">¶</a></dt> +<dd>This boolean annotation specifies that the value of the corresponding +argument (which should be either <a class="reference external" href="specification_files.html#stype-SIP_PYCALLABLE"><tt class="xref docutils literal"><span class="pre">SIP_PYCALLABLE</span></tt></a>, +<a class="reference external" href="specification_files.html#stype-SIP_PYDICT"><tt class="xref docutils literal"><span class="pre">SIP_PYDICT</span></tt></a>, <a class="reference external" href="specification_files.html#stype-SIP_PYLIST"><tt class="xref docutils literal"><span class="pre">SIP_PYLIST</span></tt></a>, <a class="reference external" href="specification_files.html#stype-SIP_PYSLICE"><tt class="xref docutils literal"><span class="pre">SIP_PYSLICE</span></tt></a>, +<a class="reference external" href="specification_files.html#stype-SIP_PYTUPLE"><tt class="xref docutils literal"><span class="pre">SIP_PYTUPLE</span></tt></a> or <a class="reference external" href="specification_files.html#stype-SIP_PYTYPE"><tt class="xref docutils literal"><span class="pre">SIP_PYTYPE</span></tt></a>) may be <tt class="xref docutils literal"><span class="pre">None</span></tt>.</dd></dl> + +<dl class="argument-annotation"> +<dt id="aanno-Array"> +<tt class="descname">Array</tt><a class="headerlink" href="#aanno-Array" title="Permalink to this definition">¶</a></dt> +<dd><p>This boolean annotation specifies that the corresponding argument refers +to an array.</p> +<p>The argument should be either a pointer to a wrapped type, a <tt class="docutils literal"><span class="pre">char</span> <span class="pre">*</span></tt> or +a <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">char</span> <span class="pre">*</span></tt>. If the argument is a character array then the +annotation also implies the <a class="reference internal" href="#aanno-Encoding"><tt class="xref docutils literal"><span class="pre">Encoding</span></tt></a> annotation with an encoding +of <tt class="docutils literal"><span class="pre">"None"</span></tt>.</p> +<p>There must be a corresponding argument with the <a class="reference internal" href="#aanno-ArraySize"><tt class="xref docutils literal"><span class="pre">ArraySize</span></tt></a> +annotation specified. The annotation may only be specified once in a list +of arguments.</p> +</dd></dl> + +<dl class="argument-annotation"> +<dt id="aanno-ArraySize"> +<tt class="descname">ArraySize</tt><a class="headerlink" href="#aanno-ArraySize" title="Permalink to this definition">¶</a></dt> +<dd>This boolean annotation specifies that the corresponding argument (which +should be either <tt class="docutils literal"><span class="pre">short</span></tt>, <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">short</span></tt>, <tt class="docutils literal"><span class="pre">int</span></tt>, <tt class="docutils literal"><span class="pre">unsigned</span></tt>, +<tt class="docutils literal"><span class="pre">long</span></tt> or <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">long</span></tt>) refers to the size of an array. There must +be a corresponding argument with the <a class="reference internal" href="#aanno-Array"><tt class="xref docutils literal"><span class="pre">Array</span></tt></a> annotation specified. +The annotation may only be specified once in a list of arguments.</dd></dl> + +<dl class="argument-annotation"> +<dt id="aanno-Constrained"> +<tt class="descname">Constrained</tt><a class="headerlink" href="#aanno-Constrained" title="Permalink to this definition">¶</a></dt> +<dd><p>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:</p> +<div class="highlight-python"><pre>// 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);</pre> +</div> +<p>This boolean annotation specifies that the corresponding argument (which +should be either <tt class="docutils literal"><span class="pre">bool</span></tt>, <tt class="docutils literal"><span class="pre">int</span></tt>, <tt class="docutils literal"><span class="pre">float</span></tt>, <tt class="docutils literal"><span class="pre">double</span></tt>, <tt class="docutils literal"><span class="pre">enum</span></tt> or a +wrapped class) must match the type without any automatic conversions. In +the context of a wrapped class the invocation of any +<a class="reference external" href="directives.html#directive-%ConvertToTypeCode"><tt class="xref docutils literal"><span class="pre">%ConvertToTypeCode</span></tt></a> is suppressed.</p> +<p>The following example gets around the above problem:</p> +<div class="highlight-python"><pre>// 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);</pre> +</div> +</dd></dl> + +<dl class="argument-annotation"> +<dt id="aanno-DocType"> +<tt class="descname">DocType</tt><a class="headerlink" href="#aanno-DocType" title="Permalink to this definition">¶</a></dt> +<dd><p> +<span class="versionmodified">New in version 4.10.</span></p> +<p>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 +<a class="reference external" href="specification_files.html#stype-SIP_PYOBJECT"><tt class="xref docutils literal"><span class="pre">SIP_PYOBJECT</span></tt></a> to provide a more specific type.</p> +</dd></dl> + +<dl class="argument-annotation"> +<dt id="aanno-DocValue"> +<tt class="descname">DocValue</tt><a class="headerlink" href="#aanno-DocValue" title="Permalink to this definition">¶</a></dt> +<dd><p> +<span class="versionmodified">New in version 4.10.</span></p> +<p>This string annotation specifies the default value of the argument as it +will appear in any generated docstrings.</p> +</dd></dl> + +<dl class="argument-annotation"> +<dt id="aanno-Encoding"> +<tt class="descname">Encoding</tt><a class="headerlink" href="#aanno-Encoding" title="Permalink to this definition">¶</a></dt> +<dd><p>This string annotation specifies that the corresponding argument (which +should be either <tt class="docutils literal"><span class="pre">char</span></tt>, <tt class="docutils literal"><span class="pre">const</span> <span class="pre">char</span></tt>, <tt class="docutils literal"><span class="pre">char</span> <span class="pre">*</span></tt> or <tt class="docutils literal"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></tt>) +refers to an encoded character or <tt class="docutils literal"><span class="pre">'\0'</span></tt> terminated encoded string with +the specified encoding. The encoding can be either <tt class="docutils literal"><span class="pre">"ASCII"</span></tt>, +<tt class="docutils literal"><span class="pre">"Latin-1"</span></tt>, <tt class="docutils literal"><span class="pre">"UTF-8"</span></tt> or <tt class="docutils literal"><span class="pre">"None"</span></tt>. An encoding of <tt class="docutils literal"><span class="pre">"None"</span></tt> means +that the corresponding argument refers to an unencoded character or string.</p> +<p>The default encoding is specified by the <a class="reference external" href="directives.html#directive-%DefaultEncoding"><tt class="xref docutils literal"><span class="pre">%DefaultEncoding</span></tt></a> +directive. If the directive is not specified then <tt class="xref docutils literal"><span class="pre">None</span></tt> is used.</p> +<p>Python v3 will use the <tt class="docutils literal"><span class="pre">bytes</span></tt> type to represent the argument if the +encoding is <tt class="docutils literal"><span class="pre">"None"</span></tt> and the <tt class="docutils literal"><span class="pre">str</span></tt> type otherwise.</p> +<p>Python v2 will use the <tt class="docutils literal"><span class="pre">str</span></tt> type to represent the argument if the +encoding is <tt class="docutils literal"><span class="pre">"None"</span></tt> and the <tt class="docutils literal"><span class="pre">unicode</span></tt> type otherwise.</p> +</dd></dl> + +<dl class="argument-annotation"> +<dt id="aanno-GetWrapper"> +<tt class="descname">GetWrapper</tt><a class="headerlink" href="#aanno-GetWrapper" title="Permalink to this definition">¶</a></dt> +<dd><p>This boolean annotation is only ever used in conjunction with handwritten +code specified with the <a class="reference external" href="directives.html#directive-%MethodCode"><tt class="xref docutils literal"><span class="pre">%MethodCode</span></tt></a> 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.</p> +<p>See the <a class="reference external" href="directives.html#directive-%MethodCode"><tt class="xref docutils literal"><span class="pre">%MethodCode</span></tt></a> directive for more detail.</p> +</dd></dl> + +<dl class="argument-annotation"> +<dt id="aanno-In"> +<tt class="descname">In</tt><a class="headerlink" href="#aanno-In" title="Permalink to this definition">¶</a></dt> +<dd><p>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.</p> +<p>For pointers to wrapped C structures or C++ class instances, <tt class="docutils literal"><span class="pre">char</span> <span class="pre">*</span></tt> and +<tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">char</span> <span class="pre">*</span></tt> then this annotation is assumed unless the <a class="reference internal" href="#aanno-Out"><tt class="xref docutils literal"><span class="pre">Out</span></tt></a> +annotation is specified.</p> +<p>For pointers to other types then this annotation must be explicitly +specified if required. The argument will be dereferenced to obtain the +actual value.</p> +<p>Both <a class="reference internal" href="#aanno-In"><tt class="xref docutils literal"><span class="pre">In</span></tt></a> and <a class="reference internal" href="#aanno-Out"><tt class="xref docutils literal"><span class="pre">Out</span></tt></a> may be specified for the same argument.</p> +</dd></dl> + +<dl class="argument-annotation"> +<dt id="aanno-KeepReference"> +<tt class="descname">KeepReference</tt><a class="headerlink" href="#aanno-KeepReference" title="Permalink to this definition">¶</a></dt> +<dd>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.</dd></dl> + +<dl class="argument-annotation"> +<dt id="aanno-NoCopy"> +<tt class="descname">NoCopy</tt><a class="headerlink" href="#aanno-NoCopy" title="Permalink to this definition">¶</a></dt> +<dd><p> +<span class="versionmodified">New in version 4.10.1.</span></p> +<p>This boolean annotation is used with arguments of virtual methods that are +a <tt class="docutils literal"><span class="pre">const</span></tt> 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.</p> +<p>If the annotation is specified then the copy is not made and the original +reference is wrapped instead and will be owned by C++.</p> +</dd></dl> + +<dl class="argument-annotation"> +<dt id="aanno-Out"> +<tt class="descname">Out</tt><a class="headerlink" href="#aanno-Out" title="Permalink to this definition">¶</a></dt> +<dd><p>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.</p> +<p>For pointers to wrapped C structures or C++ class instances, <tt class="docutils literal"><span class="pre">char</span> <span class="pre">*</span></tt> and +<tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">char</span> <span class="pre">*</span></tt> then this annotation must be explicitly specified if +required.</p> +<p>For pointers to other types then this annotation is assumed unless the +<a class="reference internal" href="#aanno-In"><tt class="xref docutils literal"><span class="pre">In</span></tt></a> annotation is specified.</p> +<p>Both <a class="reference internal" href="#aanno-In"><tt class="xref docutils literal"><span class="pre">In</span></tt></a> and <a class="reference internal" href="#aanno-Out"><tt class="xref docutils literal"><span class="pre">Out</span></tt></a> may be specified for the same argument.</p> +</dd></dl> + +<dl class="argument-annotation"> +<dt id="aanno-ResultSize"> +<tt class="descname">ResultSize</tt><a class="headerlink" href="#aanno-ResultSize" title="Permalink to this definition">¶</a></dt> +<dd>This boolean annotation is used with functions or methods that return a +<tt class="docutils literal"><span class="pre">void</span> <span class="pre">*</span></tt> or <tt class="docutils literal"><span class="pre">const</span> <span class="pre">void</span> <span class="pre">*</span></tt>. It identifies an argument that defines the +size of the block of memory whose address is being returned. This allows +the <tt class="docutils literal"><span class="pre">sip.voidptr</span></tt> 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 <tt class="docutils literal"><span class="pre">buffer()</span></tt> builtin.</dd></dl> + +<dl class="argument-annotation"> +<dt id="aanno-SingleShot"> +<tt class="descname">SingleShot</tt><a class="headerlink" href="#aanno-SingleShot" title="Permalink to this definition">¶</a></dt> +<dd>This boolean annotation is used only with arguments of type +<a class="reference external" href="specification_files.html#stype-SIP_RXOBJ_CON"><tt class="xref docutils literal"><span class="pre">SIP_RXOBJ_CON</span></tt></a> to specify that the signal connected to the slot +will only ever be emitted once. This prevents a certain class of memory +leaks.</dd></dl> + +<dl class="argument-annotation"> +<dt id="aanno-Transfer"> +<tt class="descname">Transfer</tt><a class="headerlink" href="#aanno-Transfer" title="Permalink to this definition">¶</a></dt> +<dd><p>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.</p> +<p>See <a class="reference external" href="using.html#ref-object-ownership"><em>Ownership of Objects</em></a> for more detail.</p> +</dd></dl> + +<dl class="argument-annotation"> +<dt id="aanno-TransferBack"> +<tt class="descname">TransferBack</tt><a class="headerlink" href="#aanno-TransferBack" title="Permalink to this definition">¶</a></dt> +<dd><p>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.</p> +<p>See <a class="reference external" href="using.html#ref-object-ownership"><em>Ownership of Objects</em></a> for more detail.</p> +</dd></dl> + +<dl class="argument-annotation"> +<dt id="aanno-TransferThis"> +<tt class="descname">TransferThis</tt><a class="headerlink" href="#aanno-TransferThis" title="Permalink to this definition">¶</a></dt> +<dd><p>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 <tt class="xref docutils literal"><span class="pre">None</span></tt>. In addition, the newly created instance is +associated with the argument with regard to the cyclic garbage collector.</p> +<p>In the context of a non-factory method it specifies that ownership of +<tt class="docutils literal"><span class="pre">this</span></tt> is transferred from Python to C++ if the corresponding argument is +not <tt class="xref docutils literal"><span class="pre">None</span></tt>. If it is <tt class="xref docutils literal"><span class="pre">None</span></tt> then ownership is transferred to Python.</p> +<p>The annotation may be used more that once, in which case ownership is +transferred to last instance that is not <tt class="xref docutils literal"><span class="pre">None</span></tt>.</p> +<p>See <a class="reference external" href="using.html#ref-object-ownership"><em>Ownership of Objects</em></a> for more detail.</p> +</dd></dl> + +</div> +<div class="section" id="class-annotations"> +<span id="ref-class-annos"></span><h2>Class Annotations<a class="headerlink" href="#class-annotations" title="Permalink to this headline">¶</a></h2> +<dl class="class-annotation"> +<dt id="canno-Abstract"> +<tt class="descname">Abstract</tt><a class="headerlink" href="#canno-Abstract" title="Permalink to this definition">¶</a></dt> +<dd>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.</dd></dl> + +<dl class="class-annotation"> +<dt id="canno-AllowNone"> +<tt class="descname">AllowNone</tt><a class="headerlink" href="#canno-AllowNone" title="Permalink to this definition">¶</a></dt> +<dd><p> +<span class="versionmodified">New in version 4.8.2.</span></p> +<p>Normally when a Python object is converted to a C/C++ instance <tt class="xref docutils literal"><span class="pre">None</span></tt> +is handled automatically before the class’s +<a class="reference external" href="directives.html#directive-%ConvertToTypeCode"><tt class="xref docutils literal"><span class="pre">%ConvertToTypeCode</span></tt></a> is called. This boolean annotation +specifies that the handling of <tt class="xref docutils literal"><span class="pre">None</span></tt> will be left to the +<a class="reference external" href="directives.html#directive-%ConvertToTypeCode"><tt class="xref docutils literal"><span class="pre">%ConvertToTypeCode</span></tt></a>. The annotation is ignored if the class +does not have any <a class="reference external" href="directives.html#directive-%ConvertToTypeCode"><tt class="xref docutils literal"><span class="pre">%ConvertToTypeCode</span></tt></a>.</p> +</dd></dl> + +<dl class="class-annotation"> +<dt id="canno-API"> +<tt class="descname">API</tt><a class="headerlink" href="#canno-API" title="Permalink to this definition">¶</a></dt> +<dd><p> +<span class="versionmodified">New in version 4.9.</span></p> +<p>This API range annotation is used to specify an API and corresponding +range of version numbers that the class is enabled for.</p> +<p>If a class or mapped type has different implementations enabled for +different ranges of version numbers then those ranges must not overlap.</p> +<p>See <a class="reference external" href="using.html#ref-incompat-apis"><em>Managing Incompatible APIs</em></a> for more detail.</p> +</dd></dl> + +<dl class="class-annotation"> +<dt id="canno-DelayDtor"> +<tt class="descname">DelayDtor</tt><a class="headerlink" href="#canno-DelayDtor" title="Permalink to this definition">¶</a></dt> +<dd><p>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.</p> +<p>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 +<a title="sipDelayedDtors" class="reference internal" href="#sipDelayedDtors"><tt class="xref docutils literal"><span class="pre">sipDelayedDtors()</span></tt></a> is called with the list of delayed instances. +<a title="sipDelayedDtors" class="reference internal" href="#sipDelayedDtors"><tt class="xref docutils literal"><span class="pre">sipDelayedDtors()</span></tt></a> can then choose to call (or ignore) the +destructors in any desired order.</p> +<p>The <a title="sipDelayedDtors" class="reference internal" href="#sipDelayedDtors"><tt class="xref docutils literal"><span class="pre">sipDelayedDtors()</span></tt></a> function must be specified using the +<a class="reference external" href="directives.html#directive-%ModuleCode"><tt class="xref docutils literal"><span class="pre">%ModuleCode</span></tt></a> directive.</p> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipDelayedDtors"> +void <tt class="descname">sipDelayedDtors</tt><big>(</big>const <a title="sipDelayedDtor" class="reference internal" href="#sipDelayedDtor">sipDelayedDtor</a><em> *dd_list</em><big>)</big><a class="headerlink" href="#sipDelayedDtors" title="Permalink to this definition">¶</a></dt> +<dd><table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>dd_list</em> – the linked list of delayed instances.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="ctype"> +<dt id="sipDelayedDtor"> +<tt class="descname">sipDelayedDtor</tt><a class="headerlink" href="#sipDelayedDtor" title="Permalink to this definition">¶</a></dt> +<dd><p>This structure describes a particular delayed destructor.</p> +<dl class="cmember"> +<dt id="dd_name"> +const char *<tt class="descname">dd_name</tt><a class="headerlink" href="#dd_name" title="Permalink to this definition">¶</a></dt> +<dd>This is the name of the class excluding any package or module name.</dd></dl> + +<dl class="cmember"> +<dt id="dd_ptr"> +void *<tt class="descname">dd_ptr</tt><a class="headerlink" href="#dd_ptr" title="Permalink to this definition">¶</a></dt> +<dd>This is the address of the C or C++ instance to be destroyed. It’s +exact type depends on the value of <a title="dd_isderived" class="reference internal" href="#dd_isderived"><tt class="xref docutils literal"><span class="pre">dd_isderived</span></tt></a>.</dd></dl> + +<dl class="cmember"> +<dt id="dd_isderived"> +int <tt class="descname">dd_isderived</tt><a class="headerlink" href="#dd_isderived" title="Permalink to this definition">¶</a></dt> +<dd>This is non-zero if the type of <a title="dd_ptr" class="reference internal" href="#dd_ptr"><tt class="xref docutils literal"><span class="pre">dd_ptr</span></tt></a> is actually the +generated derived class. This allows the correct destructor to be +called. See <a class="reference external" href="c_api.html#ref-derived-classes"><em>Generated Derived Classes</em></a>.</dd></dl> + +<dl class="cmember"> +<dt id="dd_next"> +<a title="sipDelayedDtor" class="reference internal" href="#sipDelayedDtor">sipDelayedDtor</a> *<tt class="descname">dd_next</tt><a class="headerlink" href="#dd_next" title="Permalink to this definition">¶</a></dt> +<dd>This is the address of the next entry in the list or zero if this is +the last one.</dd></dl> + +<p>Note that the above applies only to C and C++ instances that are owned by +Python.</p> +</dd></dl> + +<dl class="class-annotation"> +<dt id="canno-Deprecated"> +<tt class="descname">Deprecated</tt><a class="headerlink" href="#canno-Deprecated" title="Permalink to this definition">¶</a></dt> +<dd>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.</dd></dl> + +<dl class="class-annotation"> +<dt id="canno-External"> +<tt class="descname">External</tt><a class="headerlink" href="#canno-External" title="Permalink to this definition">¶</a></dt> +<dd>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.</dd></dl> + +<dl class="class-annotation"> +<dt id="canno-Metatype"> +<tt class="descname">Metatype</tt><a class="headerlink" href="#canno-Metatype" title="Permalink to this definition">¶</a></dt> +<dd><p>This dotted name annotation specifies the name of the Python type object +(i.e. the value of the <tt class="docutils literal"><span class="pre">tp_name</span></tt> field) used as the meta-type used when +creating the type object for this C structure or C++ type.</p> +<p>See the section <a class="reference external" href="using.html#ref-types-metatypes"><em>Types and Meta-types</em></a> for more details.</p> +</dd></dl> + +<dl class="class-annotation"> +<dt id="canno-NoDefaultCtors"> +<tt class="descname">NoDefaultCtors</tt><a class="headerlink" href="#canno-NoDefaultCtors" title="Permalink to this definition">¶</a></dt> +<dd>This boolean annotation is used to suppress the automatic generation of +default constructors for the class.</dd></dl> + +<dl class="class-annotation"> +<dt id="canno-PyName"> +<tt class="descname">PyName</tt><a class="headerlink" href="#canno-PyName" title="Permalink to this definition">¶</a></dt> +<dd>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.</dd></dl> + +<dl class="class-annotation"> +<dt id="canno-Supertype"> +<tt class="descname">Supertype</tt><a class="headerlink" href="#canno-Supertype" title="Permalink to this definition">¶</a></dt> +<dd><p>This dotted name annotation specifies the name of the Python type object +(i.e. the value of the <tt class="docutils literal"><span class="pre">tp_name</span></tt> field) used as the super-type used when +creating the type object for this C structure or C++ type.</p> +<p>See the section <a class="reference external" href="using.html#ref-types-metatypes"><em>Types and Meta-types</em></a> for more details.</p> +</dd></dl> + +</div> +<div class="section" id="mapped-type-annotations"> +<span id="ref-mapped-type-annos"></span><h2>Mapped Type Annotations<a class="headerlink" href="#mapped-type-annotations" title="Permalink to this headline">¶</a></h2> +<dl class="mapped-type-annotation"> +<dt id="manno-AllowNone"> +<tt class="descname">AllowNone</tt><a class="headerlink" href="#manno-AllowNone" title="Permalink to this definition">¶</a></dt> +<dd>Normally when a Python object is converted to a C/C++ instance <tt class="xref docutils literal"><span class="pre">None</span></tt> +is handled automatically before the mapped type’s +<a class="reference external" href="directives.html#directive-%ConvertToTypeCode"><tt class="xref docutils literal"><span class="pre">%ConvertToTypeCode</span></tt></a> is called. This boolean annotation +specifies that the handling of <tt class="xref docutils literal"><span class="pre">None</span></tt> will be left to the +<a class="reference external" href="directives.html#directive-%ConvertToTypeCode"><tt class="xref docutils literal"><span class="pre">%ConvertToTypeCode</span></tt></a>.</dd></dl> + +<dl class="mapped-type-annotation"> +<dt id="manno-API"> +<tt class="descname">API</tt><a class="headerlink" href="#manno-API" title="Permalink to this definition">¶</a></dt> +<dd><p> +<span class="versionmodified">New in version 4.9.</span></p> +<p>This API range annotation is used to specify an API and corresponding +range of version numbers that the mapped type is enabled for.</p> +<p>If a class or mapped type has different implementations enabled for +different ranges of version numbers then those ranges must not overlap.</p> +<p>See <a class="reference external" href="using.html#ref-incompat-apis"><em>Managing Incompatible APIs</em></a> for more detail.</p> +</dd></dl> + +<dl class="mapped-type-annotation"> +<dt id="manno-DocType"> +<tt class="descname">DocType</tt><a class="headerlink" href="#manno-DocType" title="Permalink to this definition">¶</a></dt> +<dd><p> +<span class="versionmodified">New in version 4.10.</span></p> +<p>This string annotation specifies the name of the type as it will appear in +any generated docstrings.</p> +</dd></dl> + +<dl class="mapped-type-annotation"> +<dt id="manno-NoRelease"> +<tt class="descname">NoRelease</tt><a class="headerlink" href="#manno-NoRelease" title="Permalink to this definition">¶</a></dt> +<dd>This boolean annotation is used to specify that the mapped type does not +support the <a title="sipReleaseType" class="reference external" href="c_api.html#sipReleaseType"><tt class="xref docutils literal"><span class="pre">sipReleaseType()</span></tt></a> function. Any +<a class="reference external" href="directives.html#directive-%ConvertToTypeCode"><tt class="xref docutils literal"><span class="pre">%ConvertToTypeCode</span></tt></a> should not create temporary instances of +the mapped type, i.e. it should not return <tt class="xref docutils literal"><span class="pre">SIP_TEMPORARY</span></tt>.</dd></dl> + +</div> +<div class="section" id="enum-annotations"> +<span id="ref-enum-annos"></span><h2>Enum Annotations<a class="headerlink" href="#enum-annotations" title="Permalink to this headline">¶</a></h2> +<dl class="enum-annotation"> +<dt id="eanno-PyName"> +<tt class="descname">PyName</tt><a class="headerlink" href="#eanno-PyName" title="Permalink to this definition">¶</a></dt> +<dd>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.</dd></dl> + +</div> +<div class="section" id="exception-annotations"> +<span id="ref-exception-annos"></span><h2>Exception Annotations<a class="headerlink" href="#exception-annotations" title="Permalink to this headline">¶</a></h2> +<dl class="exception-annotation"> +<dt id="xanno-Default"> +<tt class="descname">Default</tt><a class="headerlink" href="#xanno-Default" title="Permalink to this definition">¶</a></dt> +<dd>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 <tt class="docutils literal"><span class="pre">throw</span></tt> clause.</dd></dl> + +<dl class="exception-annotation"> +<dt id="xanno-PyName"> +<tt class="descname">PyName</tt><a class="headerlink" href="#xanno-PyName" title="Permalink to this definition">¶</a></dt> +<dd>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.</dd></dl> + +</div> +<div class="section" id="function-annotations"> +<span id="ref-function-annos"></span><h2>Function Annotations<a class="headerlink" href="#function-annotations" title="Permalink to this headline">¶</a></h2> +<dl class="function-annotation"> +<dt id="fanno-API"> +<tt class="descname">API</tt><a class="headerlink" href="#fanno-API" title="Permalink to this definition">¶</a></dt> +<dd><p> +<span class="versionmodified">New in version 4.9.</span></p> +<p>This API range annotation is used to specify an API and corresponding +range of version numbers that the function is enabled for.</p> +<p>See <a class="reference external" href="using.html#ref-incompat-apis"><em>Managing Incompatible APIs</em></a> for more detail.</p> +</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-AutoGen"> +<tt class="descname">AutoGen</tt><a class="headerlink" href="#fanno-AutoGen" title="Permalink to this definition">¶</a></dt> +<dd>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 <a class="reference external" href="directives.html#directive-%Feature"><tt class="xref docutils literal"><span class="pre">%Feature</span></tt></a> directive) +which must be enabled for the method to be generated.</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-Default"> +<tt class="descname">Default</tt><a class="headerlink" href="#fanno-Default" title="Permalink to this definition">¶</a></dt> +<dd>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.</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-Deprecated"> +<tt class="descname">Deprecated</tt><a class="headerlink" href="#fanno-Deprecated" title="Permalink to this definition">¶</a></dt> +<dd>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.</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-DocType"> +<tt class="descname">DocType</tt><a class="headerlink" href="#fanno-DocType" title="Permalink to this definition">¶</a></dt> +<dd><p> +<span class="versionmodified">New in version 4.10.</span></p> +<p>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 <a class="reference external" href="specification_files.html#stype-SIP_PYOBJECT"><tt class="xref docutils literal"><span class="pre">SIP_PYOBJECT</span></tt></a> to provide a more specific type.</p> +</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-Factory"> +<tt class="descname">Factory</tt><a class="headerlink" href="#fanno-Factory" title="Permalink to this definition">¶</a></dt> +<dd><p>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.</p> +<p>See <a class="reference external" href="using.html#ref-object-ownership"><em>Ownership of Objects</em></a> for more detail.</p> +</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-HoldGIL"> +<tt class="descname">HoldGIL</tt><a class="headerlink" href="#fanno-HoldGIL" title="Permalink to this definition">¶</a></dt> +<dd>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 <a class="reference external" href="using.html#ref-gil"><em>The Python Global Interpreter Lock</em></a> and the <a class="reference internal" href="#fanno-ReleaseGIL"><tt class="xref docutils literal"><span class="pre">ReleaseGIL</span></tt></a> annotation.</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-KeywordArgs"> +<tt class="descname">KeywordArgs</tt><a class="headerlink" href="#fanno-KeywordArgs" title="Permalink to this definition">¶</a></dt> +<dd><p> +<span class="versionmodified">New in version 4.10.</span></p> +<p>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.</p> +</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-__len__"> +<tt class="descname">__len__</tt><a class="headerlink" href="#fanno-__len__" title="Permalink to this definition">¶</a></dt> +<dd><p> +<span class="versionmodified">New in version 4.10.3.</span></p> +<p>This boolean annotation specifies that a <tt class="docutils literal"><span class="pre">__len__()</span></tt> method should be +automatically generated that will use the method being annotated to compute +the value that the <tt class="docutils literal"><span class="pre">__len__()</span></tt> method will return.</p> +</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-NewThread"> +<tt class="descname">NewThread</tt><a class="headerlink" href="#fanno-NewThread" title="Permalink to this definition">¶</a></dt> +<dd>This boolean annotation specifies that the function will create a new +thread.</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-NoArgParser"> +<tt class="descname">NoArgParser</tt><a class="headerlink" href="#fanno-NoArgParser" title="Permalink to this definition">¶</a></dt> +<dd>This boolean annotation is used with methods and global functions to +specify that the supplied <a class="reference external" href="directives.html#directive-%MethodCode"><tt class="xref docutils literal"><span class="pre">%MethodCode</span></tt></a> will handle the parsing +of the arguments.</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-NoCopy"> +<tt class="descname">NoCopy</tt><a class="headerlink" href="#fanno-NoCopy" title="Permalink to this definition">¶</a></dt> +<dd><p> +<span class="versionmodified">New in version 4.10.1.</span></p> +<p>This boolean annotation is used with methods and global functions that +return a <tt class="docutils literal"><span class="pre">const</span></tt> 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.</p> +<p>If the annotation is specified then the copy is not made and the original +reference is wrapped instead and will be owned by C++.</p> +</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-NoDerived"> +<tt class="descname">NoDerived</tt><a class="headerlink" href="#fanno-NoDerived" title="Permalink to this definition">¶</a></dt> +<dd>This boolean annotation is only used with C++ constructors. In many cases +SIP generates a derived class for each class being wrapped (see +<a class="reference external" href="c_api.html#ref-derived-classes"><em>Generated Derived Classes</em></a>). 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.</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-NoKeywordArgs"> +<tt class="descname">NoKeywordArgs</tt><a class="headerlink" href="#fanno-NoKeywordArgs" title="Permalink to this definition">¶</a></dt> +<dd><p> +<span class="versionmodified">New in version 4.10.</span></p> +<p>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.</p> +</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-Numeric"> +<tt class="descname">Numeric</tt><a class="headerlink" href="#fanno-Numeric" title="Permalink to this definition">¶</a></dt> +<dd>This boolean annotation specifies that the operator should be interpreted +as a numeric operator rather than a sequence operator. Python uses the +<tt class="docutils literal"><span class="pre">+</span></tt> operator for adding numbers and concatanating sequences, and the +<tt class="docutils literal"><span class="pre">*</span></tt> 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 <tt class="docutils literal"><span class="pre">-</span></tt>, <tt class="docutils literal"><span class="pre">-=</span></tt>, <tt class="docutils literal"><span class="pre">/</span></tt>, <tt class="docutils literal"><span class="pre">/=</span></tt>, +<tt class="docutils literal"><span class="pre">%</span></tt> or <tt class="docutils literal"><span class="pre">%=</span></tt> defined then it assumes that <tt class="docutils literal"><span class="pre">+</span></tt>, <tt class="docutils literal"><span class="pre">+=</span></tt>, <tt class="docutils literal"><span class="pre">*</span></tt> and +<tt class="docutils literal"><span class="pre">*=</span></tt> should be numeric operators. Otherwise, if it finds either <tt class="docutils literal"><span class="pre">[]</span></tt>, +<tt class="xref docutils literal"><span class="pre">__getitem__()</span></tt>, <tt class="xref docutils literal"><span class="pre">__setitem__()</span></tt> or <tt class="xref docutils literal"><span class="pre">__delitem__()</span></tt> defined +then it assumes that they should be sequence operators. This annotation is +used to force SIP to treat the operator as numeric.</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-PostHook"> +<tt class="descname">PostHook</tt><a class="headerlink" href="#fanno-PostHook" title="Permalink to this definition">¶</a></dt> +<dd>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.</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-PreHook"> +<tt class="descname">PreHook</tt><a class="headerlink" href="#fanno-PreHook" title="Permalink to this definition">¶</a></dt> +<dd>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.</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-PyName"> +<tt class="descname">PyName</tt><a class="headerlink" href="#fanno-PyName" title="Permalink to this definition">¶</a></dt> +<dd>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.</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-ReleaseGIL"> +<tt class="descname">ReleaseGIL</tt><a class="headerlink" href="#fanno-ReleaseGIL" title="Permalink to this definition">¶</a></dt> +<dd>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 <a class="reference external" href="using.html#ref-gil"><em>The Python Global Interpreter Lock</em></a> and the +<a class="reference internal" href="#fanno-HoldGIL"><tt class="xref docutils literal"><span class="pre">HoldGIL</span></tt></a> annotation.</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-Transfer"> +<tt class="descname">Transfer</tt><a class="headerlink" href="#fanno-Transfer" title="Permalink to this definition">¶</a></dt> +<dd><p>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.</p> +<p>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.</p> +<p>See <a class="reference external" href="using.html#ref-object-ownership"><em>Ownership of Objects</em></a> for more detail.</p> +</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-TransferBack"> +<tt class="descname">TransferBack</tt><a class="headerlink" href="#fanno-TransferBack" title="Permalink to this definition">¶</a></dt> +<dd><p>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.</p> +<p>See <a class="reference external" href="using.html#ref-object-ownership"><em>Ownership of Objects</em></a> for more detail.</p> +</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-TransferThis"> +<tt class="descname">TransferThis</tt><a class="headerlink" href="#fanno-TransferThis" title="Permalink to this definition">¶</a></dt> +<dd><p>This boolean annotation specifies that ownership of <tt class="docutils literal"><span class="pre">this</span></tt> is transferred +from Python to C++.</p> +<p>See <a class="reference external" href="using.html#ref-object-ownership"><em>Ownership of Objects</em></a> for more detail.</p> +</dd></dl> + +</div> +<div class="section" id="license-annotations"> +<span id="ref-license-annos"></span><h2>License Annotations<a class="headerlink" href="#license-annotations" title="Permalink to this headline">¶</a></h2> +<dl class="license-annotation"> +<dt id="lanno-Licensee"> +<tt class="descname">Licensee</tt><a class="headerlink" href="#lanno-Licensee" title="Permalink to this definition">¶</a></dt> +<dd><p>This optional string annotation specifies the license’s licensee. No +restrictions are placed on the contents of the string.</p> +<p>See the <a class="reference external" href="directives.html#directive-%License"><tt class="xref docutils literal"><span class="pre">%License</span></tt></a> directive.</p> +</dd></dl> + +<dl class="license-annotation"> +<dt id="lanno-Signature"> +<tt class="descname">Signature</tt><a class="headerlink" href="#lanno-Signature" title="Permalink to this definition">¶</a></dt> +<dd><p>This optional string annotation specifies the license’s signature. No +restrictions are placed on the contents of the string.</p> +<p>See the <a class="reference external" href="directives.html#directive-%License"><tt class="xref docutils literal"><span class="pre">%License</span></tt></a> directive.</p> +</dd></dl> + +<dl class="license-annotation"> +<dt id="lanno-Timestamp"> +<tt class="descname">Timestamp</tt><a class="headerlink" href="#lanno-Timestamp" title="Permalink to this definition">¶</a></dt> +<dd><p>This optional string annotation specifies the license’s timestamp. No +restrictions are placed on the contents of the string.</p> +<p>See the <a class="reference external" href="directives.html#directive-%License"><tt class="xref docutils literal"><span class="pre">%License</span></tt></a> directive.</p> +</dd></dl> + +<dl class="license-annotation"> +<dt id="lanno-Type"> +<tt class="descname">Type</tt><a class="headerlink" href="#lanno-Type" title="Permalink to this definition">¶</a></dt> +<dd><p>This string annotation specifies the license’s type. No restrictions are +placed on the contents of the string.</p> +<p>See the <a class="reference external" href="directives.html#directive-%License"><tt class="xref docutils literal"><span class="pre">%License</span></tt></a> directive.</p> +</dd></dl> + +</div> +<div class="section" id="typedef-annotations"> +<span id="ref-typedef-annos"></span><h2>Typedef Annotations<a class="headerlink" href="#typedef-annotations" title="Permalink to this headline">¶</a></h2> +<dl class="typedef-annotation"> +<dt id="tanno-NoTypeName"> +<tt class="descname">NoTypeName</tt><a class="headerlink" href="#tanno-NoTypeName" title="Permalink to this definition">¶</a></dt> +<dd><p>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.</p> +<p>Normally a typedef would be defined as follows:</p> +<div class="highlight-python"><pre>typedef bool MyBool;</pre> +</div> +<p>This would result in <tt class="docutils literal"><span class="pre">MyBool</span></tt> being used in the generated code.</p> +<p>Specifying the annotation means that <tt class="docutils literal"><span class="pre">bool</span></tt> will be used in the generated +code instead.</p> +</dd></dl> + +</div> +<div class="section" id="variable-annotations"> +<span id="ref-variable-annos"></span><h2>Variable Annotations<a class="headerlink" href="#variable-annotations" title="Permalink to this headline">¶</a></h2> +<dl class="variable-annotation"> +<dt id="vanno-DocType"> +<tt class="descname">DocType</tt><a class="headerlink" href="#vanno-DocType" title="Permalink to this definition">¶</a></dt> +<dd><p> +<span class="versionmodified">New in version 4.10.</span></p> +<p>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 <a class="reference external" href="specification_files.html#stype-SIP_PYOBJECT"><tt class="xref docutils literal"><span class="pre">SIP_PYOBJECT</span></tt></a> to provide a more specific type.</p> +</dd></dl> + +<dl class="variable-annotation"> +<dt id="vanno-PyName"> +<tt class="descname">PyName</tt><a class="headerlink" href="#vanno-PyName" title="Permalink to this definition">¶</a></dt> +<dd>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.</dd></dl> + +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference external" href="#">Annotations</a><ul> +<li><a class="reference external" href="#argument-annotations">Argument Annotations</a></li> +<li><a class="reference external" href="#class-annotations">Class Annotations</a></li> +<li><a class="reference external" href="#mapped-type-annotations">Mapped Type Annotations</a></li> +<li><a class="reference external" href="#enum-annotations">Enum Annotations</a></li> +<li><a class="reference external" href="#exception-annotations">Exception Annotations</a></li> +<li><a class="reference external" href="#function-annotations">Function Annotations</a></li> +<li><a class="reference external" href="#license-annotations">License Annotations</a></li> +<li><a class="reference external" href="#typedef-annotations">Typedef Annotations</a></li> +<li><a class="reference external" href="#variable-annotations">Variable Annotations</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="directives.html" + title="previous chapter">Directives</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="c_api.html" + title="next chapter">C API for Handwritten Code</a></p> + <div id="searchbox" style="display: none"> + <h3>Quick search</h3> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" size="18" /> + <input type="submit" value="Go" /> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </form> + <p class="searchtip" style="font-size: 90%"> + Enter search terms or a module, class or function name. + </p> + </div> + <script type="text/javascript">$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="modindex.html" title="Global Module Index" + >modules</a> |</li> + <li class="right" > + <a href="c_api.html" title="C API for Handwritten Code" + >next</a> |</li> + <li class="right" > + <a href="directives.html" title="Directives" + >previous</a> |</li> + <li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2010 Riverbank Computing Limited. + Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.4. + </div> + </body> +</html>
\ No newline at end of file diff --git a/doc/html/build_system.html b/doc/html/build_system.html new file mode 100644 index 0000000..11016d4 --- /dev/null +++ b/doc/html/build_system.html @@ -0,0 +1,1182 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + + <title>The Build System — SIP 4.10.5 Reference Guide</title> + <link rel="stylesheet" href="_static/default.css" type="text/css" /> + <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '#', + VERSION: '4.10.5', + COLLAPSE_MODINDEX: false, + FILE_SUFFIX: '.html', + HAS_SOURCE: true + }; + </script> + <script type="text/javascript" src="_static/jquery.js"></script> + <script type="text/javascript" src="_static/doctools.js"></script> + <link rel="top" title="SIP 4.10.5 Reference Guide" href="index.html" /> + <link rel="next" title="Building Your Extension with distutils" href="distutils.html" /> + <link rel="prev" title="Python API for Applications" href="python_api.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="modindex.html" title="Global Module Index" + accesskey="M">modules</a> |</li> + <li class="right" > + <a href="distutils.html" title="Building Your Extension with distutils" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="python_api.html" title="Python API for Applications" + accesskey="P">previous</a> |</li> + <li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="module-sipconfig"> +<span id="ref-build-system"></span><h1>The Build System<a class="headerlink" href="#module-sipconfig" title="Permalink to this headline">¶</a></h1> +<p>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.</p> +<p>The build system is implemented as a pure Python module called <tt class="xref docutils literal"><span class="pre">sipconfig</span></tt> +that contains a number of classes and functions. Using this module you can +write bespoke configuration scripts (e.g. PyQt’s <tt class="docutils literal"><span class="pre">configure.py</span></tt>) or use it +with other Python based build systems (e.g. +<a class="reference external" href="http://www.python.org/sigs/distutils-sig/distutils.html">Distutils</a> and +<a class="reference external" href="http://www.scons.org">SCons</a>).</p> +<p>An important feature of SIP is the ability to generate bindings that are built +on top of existing bindings. For example, both +<a class="reference external" href="http://www.riverbankcomputing.com/software/pykde/">PyKDE</a> and +<a class="reference external" href="http://pyqwt.sourceforge.net/">PyQwt</a> 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, <tt class="docutils literal"><span class="pre">pyqtconfig</span></tt>, 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.</p> +<dl class="function"> +<dt id="sipconfig.create_config_module"> +<tt class="descclassname">sipconfig.</tt><tt class="descname">create_config_module</tt><big>(</big><em>module</em>, <em>template</em>, <em>content</em><span class="optional">[</span>, <em>macros=None</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#sipconfig.create_config_module" title="Permalink to this definition">¶</a></dt> +<dd><p>This creates a configuration module (e.g. <tt class="docutils literal"><span class="pre">pyqtconfig</span></tt>) from a template +file and a string.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><em>module</em> – the name of the configuration module file to create.</li> +<li><em>template</em> – the name of the template file.</li> +<li><em>content</em> – a string which replaces every occurence of the pattern +<tt class="docutils literal"><span class="pre">@SIP_CONFIGURATION@</span></tt> in the template file. The content string is +usually created from a Python dictionary using +<a title="sipconfig.create_content" class="reference internal" href="#sipconfig.create_content"><tt class="xref docutils literal"><span class="pre">sipconfig.create_content()</span></tt></a>. <em>content</em> may also be a +dictionary, in which case <a title="sipconfig.create_content" class="reference internal" href="#sipconfig.create_content"><tt class="xref docutils literal"><span class="pre">sipconfig.create_content()</span></tt></a> is +automatically called to convert it to a string.</li> +<li><em>macros</em> – an optional dictionary of platform specific build macros. It is only +used if <a title="sipconfig.create_content" class="reference internal" href="#sipconfig.create_content"><tt class="xref docutils literal"><span class="pre">sipconfig.create_content()</span></tt></a> is called automatically to +convert a <em>content</em> dictionary to a string.</li> +</ul> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="sipconfig.create_content"> +<tt class="descclassname">sipconfig.</tt><tt class="descname">create_content</tt><big>(</big><em>dict</em><span class="optional">[</span>, <em>macros=None</em><span class="optional">]</span><big>)</big> → string<a class="headerlink" href="#sipconfig.create_content" title="Permalink to this definition">¶</a></dt> +<dd><p>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 +<a title="sipconfig.create_config_module" class="reference internal" href="#sipconfig.create_config_module"><tt class="xref docutils literal"><span class="pre">sipconfig.create_config_module()</span></tt></a>.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><em>dict</em> – the Python dictionary to convert.</li> +<li><em>macros</em> – the optional dictionary of platform specific build macros.</li> +</ul> +</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the string representation of the dictionary.</p> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="sipconfig.create_wrapper"> +<tt class="descclassname">sipconfig.</tt><tt class="descname">create_wrapper</tt><big>(</big><em>script</em>, <em>wrapper</em><span class="optional">[</span>, <em>gui=0</em><span class="optional">[</span>, <em>use_arch=''</em><span class="optional">]</span><span class="optional">]</span><big>)</big> → string<a class="headerlink" href="#sipconfig.create_wrapper" title="Permalink to this definition">¶</a></dt> +<dd><p>This creates a platform dependent executable wrapper around a Python +script.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><em>script</em> – the full pathname of the script.</li> +<li><em>wrapper</em> – the full pathname of the wrapper to create, excluding any platform +specific extension.</li> +<li><em>gui</em> – is non-zero if a GUI enabled version of the interpreter should be used +on platforms that require it.</li> +<li><em>use_arch</em> – is the MacOS/X architecture to invoke python with.</li> +</ul> +</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the platform specific name of the wrapper.</p> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="sipconfig.error"> +<tt class="descclassname">sipconfig.</tt><tt class="descname">error</tt><big>(</big><em>msg</em><big>)</big><a class="headerlink" href="#sipconfig.error" title="Permalink to this definition">¶</a></dt> +<dd><p>This displays an error message on <tt class="docutils literal"><span class="pre">stderr</span></tt> and calls <tt class="docutils literal"><span class="pre">sys.exit(1)</span></tt>.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>msg</em> – the text of the message and should not include any newline characters.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="sipconfig.format"> +<tt class="descclassname">sipconfig.</tt><tt class="descname">format</tt><big>(</big><em>msg</em><span class="optional">[</span>, <em>leftmargin=0</em><span class="optional">[</span>, <em>rightmargin=78</em><span class="optional">]</span><span class="optional">]</span><big>)</big> → string<a class="headerlink" href="#sipconfig.format" title="Permalink to this definition">¶</a></dt> +<dd><p>This formats a message by inserting newline characters at appropriate +places.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><em>msg</em> – the text of the message and should not include any newline characters.</li> +<li><em>leftmargin</em> – the optional position of the left margin.</li> +<li><em>rightmargin</em> – the optional position of the right margin.</li> +</ul> +</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the formatted message.</p> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="sipconfig.inform"> +<tt class="descclassname">sipconfig.</tt><tt class="descname">inform</tt><big>(</big><em>msg</em><big>)</big><a class="headerlink" href="#sipconfig.inform" title="Permalink to this definition">¶</a></dt> +<dd><p>This displays an information message on <tt class="docutils literal"><span class="pre">stdout</span></tt>.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>msg</em> – the text of the message and should not include any newline characters.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="sipconfig.parse_build_macros"> +<tt class="descclassname">sipconfig.</tt><tt class="descname">parse_build_macros</tt><big>(</big><em>filename</em>, <em>names</em><span class="optional">[</span>, <em>overrides=None</em><span class="optional">[</span>, <em>properties=None</em><span class="optional">]</span><span class="optional">]</span><big>)</big> → dict<a class="headerlink" href="#sipconfig.parse_build_macros" title="Permalink to this definition">¶</a></dt> +<dd><p>This parses a <tt class="docutils literal"><span class="pre">qmake</span></tt> 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.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><em>filename</em> – the name of the file to parse.</li> +<li><em>names</em> – the list of the macro names to extract from the file.</li> +<li><em>overrides</em> – the optional list of macro names and values that modify those found in +the file. They are of the form <tt class="docutils literal"><span class="pre">name=value</span></tt> (in which case the value +replaces the value found in the file) or <tt class="docutils literal"><span class="pre">name+=value</span></tt> (in which case +the value is appended to the value found in the file).</li> +<li><em>properties</em> – the optional dictionary of property name and values that are used to +resolve any expressions of the form <tt class="docutils literal"><span class="pre">$[name]</span></tt> in the file.</li> +</ul> +</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the dictionary of parsed macros or <tt class="xref docutils literal"><span class="pre">None</span></tt> if any of the overrides +were invalid.</p> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="sipconfig.read_version"> +<tt class="descclassname">sipconfig.</tt><tt class="descname">read_version</tt><big>(</big><em>filename</em>, <em>description</em><span class="optional">[</span>, <em>numdefine=None</em><span class="optional">[</span>, <em>strdefine=None</em><span class="optional">]</span><span class="optional">]</span><big>)</big> → integer, string<a class="headerlink" href="#sipconfig.read_version" title="Permalink to this definition">¶</a></dt> +<dd><p>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 +<tt class="docutils literal"><span class="pre">#define</span></tt> of a numeric (hexadecimal or decimal) value and/or a string +value.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><em>filename</em> – the name of the file to read.</li> +<li><em>description</em> – a descriptive name of the package used in error messages.</li> +<li><em>numdefine</em> – the optional name of the <tt class="docutils literal"><span class="pre">#define</span></tt> of the version as a number. If it +is <tt class="xref docutils literal"><span class="pre">None</span></tt> then the numeric version is ignored.</li> +<li><em>strdefine</em> – the optional name of the <tt class="docutils literal"><span class="pre">#define</span></tt> of the version as a string. If it +is <tt class="xref docutils literal"><span class="pre">None</span></tt> then the string version is ignored.</li> +</ul> +</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">a tuple of the numeric and string versions. <a title="sipconfig.error" class="reference internal" href="#sipconfig.error"><tt class="xref docutils literal"><span class="pre">sipconfig.error()</span></tt></a> +is called if either were required but could not be found.</p> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="sipconfig.version_to_sip_tag"> +<tt class="descclassname">sipconfig.</tt><tt class="descname">version_to_sip_tag</tt><big>(</big><em>version</em>, <em>tags</em>, <em>description</em><big>)</big> → string<a class="headerlink" href="#sipconfig.version_to_sip_tag" title="Permalink to this definition">¶</a></dt> +<dd><p>This converts a version number to a SIP version tag. SIP uses the +<a class="reference external" href="directives.html#directive-%Timeline"><tt class="xref docutils literal"><span class="pre">%Timeline</span></tt></a> 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.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><em>version</em> – 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.)</li> +<li><em>tags</em> – 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 <em>version</em>.</li> +<li><em>description</em> – a descriptive name of the C/C++ library used in error messages.</li> +</ul> +</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the SIP version tag. <a title="sipconfig.error" class="reference internal" href="#sipconfig.error"><tt class="xref docutils literal"><span class="pre">sipconfig.error()</span></tt></a> is called if the C/C++ +library version number did not correspond to a SIP version tag.</p> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="sipconfig.version_to_string"> +<tt class="descclassname">sipconfig.</tt><tt class="descname">version_to_string</tt><big>(</big><em>v</em><big>)</big> → string<a class="headerlink" href="#sipconfig.version_to_string" title="Permalink to this definition">¶</a></dt> +<dd><p>This converts a 3 part version number encoded as a hexadecimal value to a +string.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>v</em> – the version number.</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body">a string.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="class"> +<dt id="sipconfig.Configuration"> +<em class="property">class </em><tt class="descclassname">sipconfig.</tt><tt class="descname">Configuration</tt><a class="headerlink" href="#sipconfig.Configuration" title="Permalink to this definition">¶</a></dt> +<dd><p>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.</p> +<p>The following configuration values are provided:</p> +<dl class="attribute"> +<dt id="sipconfig.Configuration.default_bin_dir"> +<tt class="descname">default_bin_dir</tt><a class="headerlink" href="#sipconfig.Configuration.default_bin_dir" title="Permalink to this definition">¶</a></dt> +<dd>The name of the directory where executables should be installed by +default.</dd></dl> + +<dl class="attribute"> +<dt id="sipconfig.Configuration.default_mod_dir"> +<tt class="descname">default_mod_dir</tt><a class="headerlink" href="#sipconfig.Configuration.default_mod_dir" title="Permalink to this definition">¶</a></dt> +<dd>The name of the directory where SIP generated modules should be +installed by default.</dd></dl> + +<dl class="attribute"> +<dt id="sipconfig.Configuration.default_sip_dir"> +<tt class="descname">default_sip_dir</tt><a class="headerlink" href="#sipconfig.Configuration.default_sip_dir" title="Permalink to this definition">¶</a></dt> +<dd>The name of the base directory where the <tt class="docutils literal"><span class="pre">.sip</span></tt> 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 <tt class="docutils literal"><span class="pre">.sip</span></tt> files +should be installed in the sub-directory. The <tt class="docutils literal"><span class="pre">.sip</span></tt> files only need +to be installed if you might want to build other bindings based on +them.</dd></dl> + +<dl class="attribute"> +<dt id="sipconfig.Configuration.platform"> +<tt class="descname">platform</tt><a class="headerlink" href="#sipconfig.Configuration.platform" title="Permalink to this definition">¶</a></dt> +<dd>The name of the platform/compiler for which the build system has been +configured for.</dd></dl> + +<dl class="attribute"> +<dt id="sipconfig.Configuration.py_conf_inc_dir"> +<tt class="descname">py_conf_inc_dir</tt><a class="headerlink" href="#sipconfig.Configuration.py_conf_inc_dir" title="Permalink to this definition">¶</a></dt> +<dd>The name of the directory containing the <tt class="docutils literal"><span class="pre">pyconfig.h</span></tt> header file.</dd></dl> + +<dl class="attribute"> +<dt id="sipconfig.Configuration.py_inc_dir"> +<tt class="descname">py_inc_dir</tt><a class="headerlink" href="#sipconfig.Configuration.py_inc_dir" title="Permalink to this definition">¶</a></dt> +<dd>The name of the directory containing the <tt class="docutils literal"><span class="pre">Python.h</span></tt> header file.</dd></dl> + +<dl class="attribute"> +<dt id="sipconfig.Configuration.py_lib_dir"> +<tt class="descname">py_lib_dir</tt><a class="headerlink" href="#sipconfig.Configuration.py_lib_dir" title="Permalink to this definition">¶</a></dt> +<dd>The name of the directory containing the Python interpreter library.</dd></dl> + +<dl class="attribute"> +<dt id="sipconfig.Configuration.py_version"> +<tt class="descname">py_version</tt><a class="headerlink" href="#sipconfig.Configuration.py_version" title="Permalink to this definition">¶</a></dt> +<dd>The Python version as a 3 part hexadecimal number (e.g. v2.3.3 is +represented as <tt class="docutils literal"><span class="pre">0x020303</span></tt>).</dd></dl> + +<dl class="attribute"> +<dt id="sipconfig.Configuration.sip_bin"> +<tt class="descname">sip_bin</tt><a class="headerlink" href="#sipconfig.Configuration.sip_bin" title="Permalink to this definition">¶</a></dt> +<dd>The full pathname of the SIP executable.</dd></dl> + +<dl class="attribute"> +<dt id="sipconfig.Configuration.sip_config_args"> +<tt class="descname">sip_config_args</tt><a class="headerlink" href="#sipconfig.Configuration.sip_config_args" title="Permalink to this definition">¶</a></dt> +<dd>The command line passed to <tt class="docutils literal"><span class="pre">configure.py</span></tt> when SIP was configured.</dd></dl> + +<dl class="attribute"> +<dt id="sipconfig.Configuration.sip_inc_dir"> +<tt class="descname">sip_inc_dir</tt><a class="headerlink" href="#sipconfig.Configuration.sip_inc_dir" title="Permalink to this definition">¶</a></dt> +<dd>The name of the directory containing the <tt class="docutils literal"><span class="pre">sip.h</span></tt> header file.</dd></dl> + +<dl class="attribute"> +<dt id="sipconfig.Configuration.sip_mod_dir"> +<tt class="descname">sip_mod_dir</tt><a class="headerlink" href="#sipconfig.Configuration.sip_mod_dir" title="Permalink to this definition">¶</a></dt> +<dd>The name of the directory containing the SIP module.</dd></dl> + +<dl class="attribute"> +<dt id="sipconfig.Configuration.sip_version"> +<tt class="descname">sip_version</tt><a class="headerlink" href="#sipconfig.Configuration.sip_version" title="Permalink to this definition">¶</a></dt> +<dd>The SIP version as a 3 part hexadecimal number (e.g. v4.0.0 is +represented as <tt class="docutils literal"><span class="pre">0x040000</span></tt>).</dd></dl> + +<dl class="attribute"> +<dt id="sipconfig.Configuration.sip_version_str"> +<tt class="descname">sip_version_str</tt><a class="headerlink" href="#sipconfig.Configuration.sip_version_str" title="Permalink to this definition">¶</a></dt> +<dd>The SIP version as a string. For development snapshots it will start +with <tt class="docutils literal"><span class="pre">snapshot-</span></tt>.</dd></dl> + +<dl class="attribute"> +<dt id="sipconfig.Configuration.universal"> +<tt class="descname">universal</tt><a class="headerlink" href="#sipconfig.Configuration.universal" title="Permalink to this definition">¶</a></dt> +<dd>The name of the MacOS/X SDK used when creating universal binaries.</dd></dl> + +<dl class="attribute"> +<dt id="sipconfig.Configuration.arch"> +<tt class="descname">arch</tt><a class="headerlink" href="#sipconfig.Configuration.arch" title="Permalink to this definition">¶</a></dt> +<dd>The space separated MacOS/X architectures to build.</dd></dl> + +<dl class="method"> +<dt id="sipconfig.Configuration.__init__"> +<tt class="descname">__init__</tt><big>(</big><span class="optional">[</span><em>sub_cfg=None</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#sipconfig.Configuration.__init__" title="Permalink to this definition">¶</a></dt> +<dd><table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>sub_cfg</em> – an optional list of sub-class configurations. It should only be +used by the <tt class="docutils literal"><span class="pre">__init__()</span></tt> method of a sub-class to append its own +dictionary of configuration values before passing the list to its +super-class.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="sipconfig.Configuration.build_macros"> +<tt class="descname">build_macros</tt><big>(</big><big>)</big> → dict<a class="headerlink" href="#sipconfig.Configuration.build_macros" title="Permalink to this definition">¶</a></dt> +<dd><p>Get the dictionary of platform specific build macros.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body">the macros dictionary.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="sipconfig.Configuration.set_build_macros"> +<tt class="descname">set_build_macros</tt><big>(</big><em>macros</em><big>)</big><a class="headerlink" href="#sipconfig.Configuration.set_build_macros" title="Permalink to this definition">¶</a></dt> +<dd><p>Set the dictionary of platform specific build macros to be used when +generating Makefiles. Normally there is no need to change the default +macros.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>macros</em> – the macros dictionary.</td> +</tr> +</tbody> +</table> +</dd></dl> + +</dd></dl> + +<dl class="class"> +<dt id="sipconfig.Makefile"> +<em class="property">class </em><tt class="descclassname">sipconfig.</tt><tt class="descname">Makefile</tt><a class="headerlink" href="#sipconfig.Makefile" title="Permalink to this definition">¶</a></dt> +<dd><p>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.</p> +<p>The following instance attributes are provided to help in fine tuning the +generated Makefile:</p> +<dl class="attribute"> +<dt id="sipconfig.Makefile.chkdir"> +<tt class="descname">chkdir</tt><a class="headerlink" href="#sipconfig.Makefile.chkdir" title="Permalink to this definition">¶</a></dt> +<dd>A string that will check for the existence of a directory.</dd></dl> + +<dl class="attribute"> +<dt id="sipconfig.Makefile.config"> +<tt class="descname">config</tt><a class="headerlink" href="#sipconfig.Makefile.config" title="Permalink to this definition">¶</a></dt> +<dd>A reference to the <em>configuration</em> argument that was passed to +<a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">Makefile.__init__()</span></tt></a>.</dd></dl> + +<dl class="attribute"> +<dt id="sipconfig.Makefile.console"> +<tt class="descname">console</tt><a class="headerlink" href="#sipconfig.Makefile.console" title="Permalink to this definition">¶</a></dt> +<dd>A reference to the <em>console</em> argument that was passed to the +<a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">Makefile.__init__()</span></tt></a>.</dd></dl> + +<dl class="attribute"> +<dt id="sipconfig.Makefile.copy"> +<tt class="descname">copy</tt><a class="headerlink" href="#sipconfig.Makefile.copy" title="Permalink to this definition">¶</a></dt> +<dd>A string that will copy a file.</dd></dl> + +<dl class="attribute"> +<dt id="sipconfig.Makefile.extra_cflags"> +<tt class="descname">extra_cflags</tt><a class="headerlink" href="#sipconfig.Makefile.extra_cflags" title="Permalink to this definition">¶</a></dt> +<dd>A list of additional flags passed to the C compiler.</dd></dl> + +<dl class="attribute"> +<dt id="sipconfig.Makefile.extra_cxxflags"> +<tt class="descname">extra_cxxflags</tt><a class="headerlink" href="#sipconfig.Makefile.extra_cxxflags" title="Permalink to this definition">¶</a></dt> +<dd>A list of additional flags passed to the C++ compiler.</dd></dl> + +<dl class="attribute"> +<dt id="sipconfig.Makefile.extra_defines"> +<tt class="descname">extra_defines</tt><a class="headerlink" href="#sipconfig.Makefile.extra_defines" title="Permalink to this definition">¶</a></dt> +<dd>A list of additional macro names passed to the C/C++ preprocessor.</dd></dl> + +<dl class="attribute"> +<dt id="sipconfig.Makefile.extra_include_dirs"> +<tt class="descname">extra_include_dirs</tt><a class="headerlink" href="#sipconfig.Makefile.extra_include_dirs" title="Permalink to this definition">¶</a></dt> +<dd>A list of additional include directories passed to the C/C++ +preprocessor.</dd></dl> + +<dl class="attribute"> +<dt id="sipconfig.Makefile.extra_lflags"> +<tt class="descname">extra_lflags</tt><a class="headerlink" href="#sipconfig.Makefile.extra_lflags" title="Permalink to this definition">¶</a></dt> +<dd>A list of additional flags passed to the linker.</dd></dl> + +<dl class="attribute"> +<dt id="sipconfig.Makefile.extra_lib_dirs"> +<tt class="descname">extra_lib_dirs</tt><a class="headerlink" href="#sipconfig.Makefile.extra_lib_dirs" title="Permalink to this definition">¶</a></dt> +<dd>A list of additional library directories passed to the linker.</dd></dl> + +<dl class="attribute"> +<dt id="sipconfig.Makefile.extra_libs"> +<tt class="descname">extra_libs</tt><a class="headerlink" href="#sipconfig.Makefile.extra_libs" title="Permalink to this definition">¶</a></dt> +<dd>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).</dd></dl> + +<dl class="attribute"> +<dt id="sipconfig.Makefile.generator"> +<tt class="descname">generator</tt><a class="headerlink" href="#sipconfig.Makefile.generator" title="Permalink to this definition">¶</a></dt> +<dd>A string that defines the platform specific style of Makefile. The +only supported values are <tt class="docutils literal"><span class="pre">UNIX</span></tt>, <tt class="docutils literal"><span class="pre">MSVC</span></tt>, <tt class="docutils literal"><span class="pre">MSVC.NET</span></tt>, <tt class="docutils literal"><span class="pre">MINGW</span></tt> +and <tt class="docutils literal"><span class="pre">BMAKE</span></tt>.</dd></dl> + +<dl class="attribute"> +<dt id="sipconfig.Makefile.mkdir"> +<tt class="descname">mkdir</tt><a class="headerlink" href="#sipconfig.Makefile.mkdir" title="Permalink to this definition">¶</a></dt> +<dd>A string that will create a directory.</dd></dl> + +<dl class="attribute"> +<dt id="sipconfig.Makefile.rm"> +<tt class="descname">rm</tt><a class="headerlink" href="#sipconfig.Makefile.rm" title="Permalink to this definition">¶</a></dt> +<dd>A string that will remove a file.</dd></dl> + +<dl class="method"> +<dt id="sipconfig.Makefile.__init__"> +<tt class="descname">__init__</tt><big>(</big><em>configuration</em><span class="optional">[</span>, <em>console=0</em><span class="optional">[</span>, <em>qt=0</em><span class="optional">[</span>, <em>opengl=0</em><span class="optional">[</span>, <em>python=0</em><span class="optional">[</span>, <em>threaded=0</em><span class="optional">[</span>, <em>warnings=None</em><span class="optional">[</span>, <em>debug=0</em><span class="optional">[</span>, <em>dir=None</em><span class="optional">[</span>, <em>makefile="Makefile"</em><span class="optional">[</span>, <em>installs=None</em><span class="optional">[</span>, <em>universal=None</em><span class="optional">[</span>, <em>arch=None</em><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><big>)</big><a class="headerlink" href="#sipconfig.Makefile.__init__" title="Permalink to this definition">¶</a></dt> +<dd><table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><em>configuration</em> – the current configuration and is an instance of the +<a title="sipconfig.Configuration" class="reference internal" href="#sipconfig.Configuration"><tt class="xref docutils literal"><span class="pre">Configuration</span></tt></a> class or a sub-class.</li> +<li><em>console</em> – is set if the target is a console (rather than GUI) target. This +only affects Windows and is ignored on other platforms.</li> +<li><em>qt</em> – 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.</li> +<li><em>opengl</em> – is set if the target uses OpenGL.</li> +<li><em>python</em> – is set if the target uses Python.h.</li> +<li><em>threaded</em> – is set if the target requires thread support. It is set +automatically if the target uses Qt and Qt has thread support +enabled.</li> +<li><em>warnings</em> – is set if compiler warning messages should be enabled. The default +of <tt class="xref docutils literal"><span class="pre">None</span></tt> means that warnings are enabled for SIP v4.x and +disabled for SIP v3.x.</li> +<li><em>debug</em> – is set if debugging symbols should be generated.</li> +<li><em>dir</em> – 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 <tt class="xref docutils literal"><span class="pre">None</span></tt> means the current directory is used.</li> +<li><em>makefile</em> – the name of the generated Makefile.</li> +<li><em>installs</em> – 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.</li> +<li><em>universal</em> – the name of the SDK if universal binaries are to be created under +MacOS/X. If it is <tt class="xref docutils literal"><span class="pre">None</span></tt> then the value is taken from the +configuration.</li> +<li><em>arch</em> – the space separated MacOS/X architectures to build. If it is +<tt class="xref docutils literal"><span class="pre">None</span></tt> then the value is taken from the configuration.</li> +</ul> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="sipconfig.Makefile.clean_build_file_objects"> +<tt class="descname">clean_build_file_objects</tt><big>(</big><em>mfile</em>, <em>build</em><big>)</big><a class="headerlink" href="#sipconfig.Makefile.clean_build_file_objects" title="Permalink to this definition">¶</a></dt> +<dd><p>This generates the Makefile commands that will remove any files +generated during the build of the default target.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><em>mfile</em> – the Python file object of the Makefile.</li> +<li><em>build</em> – the dictionary created from parsing the build file.</li> +</ul> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="sipconfig.Makefile.finalise"> +<tt class="descname">finalise</tt><big>(</big><big>)</big><a class="headerlink" href="#sipconfig.Makefile.finalise" title="Permalink to this definition">¶</a></dt> +<dd>This is called just before the Makefile is generated to ensure that it +is fully configured. It must be reimplemented by a sub-class.</dd></dl> + +<dl class="method"> +<dt id="sipconfig.Makefile.generate"> +<tt class="descname">generate</tt><big>(</big><big>)</big><a class="headerlink" href="#sipconfig.Makefile.generate" title="Permalink to this definition">¶</a></dt> +<dd>This generates the Makefile.</dd></dl> + +<dl class="method"> +<dt id="sipconfig.Makefile.generate_macros_and_rules"> +<tt class="descname">generate_macros_and_rules</tt><big>(</big><em>mfile</em><big>)</big><a class="headerlink" href="#sipconfig.Makefile.generate_macros_and_rules" title="Permalink to this definition">¶</a></dt> +<dd><p>This is the default implementation of the Makefile macros and rules +generation.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>mfile</em> – the Python file object of the Makefile.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="sipconfig.Makefile.generate_target_clean"> +<tt class="descname">generate_target_clean</tt><big>(</big><em>mfile</em><big>)</big><a class="headerlink" href="#sipconfig.Makefile.generate_target_clean" title="Permalink to this definition">¶</a></dt> +<dd><p>This is the default implementation of the Makefile clean target +generation.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>mfile</em> – the Python file object of the Makefile.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="sipconfig.Makefile.generate_target_default"> +<tt class="descname">generate_target_default</tt><big>(</big><em>mfile</em><big>)</big><a class="headerlink" href="#sipconfig.Makefile.generate_target_default" title="Permalink to this definition">¶</a></dt> +<dd><p>This is the default implementation of the Makefile default target +generation.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>mfile</em> – the Python file object of the Makefile.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="sipconfig.Makefile.generate_target_install"> +<tt class="descname">generate_target_install</tt><big>(</big><em>mfile</em><big>)</big><a class="headerlink" href="#sipconfig.Makefile.generate_target_install" title="Permalink to this definition">¶</a></dt> +<dd><p>This is the default implementation of the Makefile install target +generation.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>mfile</em> – the Python file object of the Makefile.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="sipconfig.Makefile.install_file"> +<tt class="descname">install_file</tt><big>(</big><em>mfile</em>, <em>src</em>, <em>dst</em><span class="optional">[</span>, <em>strip=0</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#sipconfig.Makefile.install_file" title="Permalink to this definition">¶</a></dt> +<dd><p>This generates the Makefile commands to install one or more files to a +directory.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><em>mfile</em> – the Python file object of the Makefile.</li> +<li><em>src</em> – the name of a single file to install or a list of a number of files +to install.</li> +<li><em>dst</em> – the name of the destination directory.</li> +<li><em>strip</em> – is set if the files should be stripped of unneeded symbols after +having been installed.</li> +</ul> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="sipconfig.Makefile.optional_list"> +<tt class="descname">optional_list</tt><big>(</big><em>name</em><big>)</big> → list<a class="headerlink" href="#sipconfig.Makefile.optional_list" title="Permalink to this definition">¶</a></dt> +<dd><p>This returns an optional Makefile macro as a list.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>name</em> – the name of the macro.</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body">the macro as a list.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="sipconfig.Makefile.optional_string"> +<tt class="descname">optional_string</tt><big>(</big><em>name</em><span class="optional">[</span>, <em>default=""</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#sipconfig.Makefile.optional_string" title="Permalink to this definition">¶</a></dt> +<dd><p>This returns an optional Makefile macro as a string.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><em>name</em> – the name of the macro.</li> +<li><em>default</em> – the optional default value of the macro.</li> +</ul> +</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the macro as a string.</p> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="sipconfig.Makefile.parse_build_file"> +<tt class="descname">parse_build_file</tt><big>(</big><em>filename</em><big>)</big> → dict<a class="headerlink" href="#sipconfig.Makefile.parse_build_file" title="Permalink to this definition">¶</a></dt> +<dd><p>This parses a build file (created with the <a class="reference external" href="command_line.html#cmdoption-sip-b"><em class="xref">-b</em></a> SIP +command line option) and converts it to a dictionary. It can also +validate an existing dictionary created through other means.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>filename</em> – 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 <tt class="docutils literal"><span class="pre">target</span></tt>; the names of all source files keyed by <tt class="docutils literal"><span class="pre">sources</span></tt>; +and, optionally, the names of all header files keyed by +<tt class="docutils literal"><span class="pre">headers</span></tt>.</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body">a dictionary corresponding to the parsed build file.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="sipconfig.Makefile.platform_lib"> +<tt class="descname">platform_lib</tt><big>(</big><em>clib</em><span class="optional">[</span>, <em>framework=0</em><span class="optional">]</span><big>)</big> → string<a class="headerlink" href="#sipconfig.Makefile.platform_lib" title="Permalink to this definition">¶</a></dt> +<dd><p>This converts a library name to a platform specific form.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><em>clib</em> – the name of the library in cannonical form.</li> +<li><em>framework</em> – is set if the library is implemented as a MacOS framework.</li> +</ul> +</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the platform specific name.</p> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="sipconfig.Makefile.ready"> +<tt class="descname">ready</tt><big>(</big><big>)</big><a class="headerlink" href="#sipconfig.Makefile.ready" title="Permalink to this definition">¶</a></dt> +<dd>This is called to ensure that the Makefile is fully configured. It is +normally called automatically when needed.</dd></dl> + +<dl class="method"> +<dt id="sipconfig.Makefile.required_string"> +<tt class="descname">required_string</tt><big>(</big><em>name</em><big>)</big> → string<a class="headerlink" href="#sipconfig.Makefile.required_string" title="Permalink to this definition">¶</a></dt> +<dd><p>This returns a required Makefile macro as a string.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>name</em> – the name of the macro.</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body">the macro as a string. An exception is raised if the macro does +not exist or has an empty value.</td> +</tr> +</tbody> +</table> +</dd></dl> + +</dd></dl> + +<dl class="class"> +<dt id="sipconfig.ModuleMakefile"> +<em class="property">class </em><tt class="descclassname">sipconfig.</tt><tt class="descname">ModuleMakefile</tt><a class="headerlink" href="#sipconfig.ModuleMakefile" title="Permalink to this definition">¶</a></dt> +<dd><p>This class is derived from <a title="sipconfig.Makefile" class="reference internal" href="#sipconfig.Makefile"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile</span></tt></a>.</p> +<p>This class encapsulates a Makefile to build a generic Python extension +module.</p> +<dl class="method"> +<dt id="sipconfig.ModuleMakefile.__init__"> +<tt class="descname">__init__</tt><big>(</big><em>self</em>, <em>configuration</em>, <em>build_file</em><span class="optional">[</span>, <em>install_dir=None</em><span class="optional">[</span>, <em>static=0</em><span class="optional">[</span>, <em>console=0</em><span class="optional">[</span>, <em>opengl=0</em><span class="optional">[</span>, <em>threaded=0</em><span class="optional">[</span>, <em>warnings=None</em><span class="optional">[</span>, <em>debug=0</em><span class="optional">[</span>, <em>dir=None</em><span class="optional">[</span>, <em>makefile="Makefile"</em><span class="optional">[</span>, <em>installs=None</em><span class="optional">[</span>, <em>strip=1</em><span class="optional">[</span>, <em>export_all=0</em><span class="optional">[</span>, <em>universal=None</em><span class="optional">[</span>, <em>arch=None</em><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><big>)</big><a class="headerlink" href="#sipconfig.ModuleMakefile.__init__" title="Permalink to this definition">¶</a></dt> +<dd><table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><em>configuration</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>build_file</em> – the name of the build file. Build files are generated using the +<a class="reference external" href="command_line.html#cmdoption-sip-b"><em class="xref">-b</em></a> SIP command line option.</li> +<li><em>install_dir</em> – the name of the directory where the module will be optionally +installed.</li> +<li><em>static</em> – is set if the module should be built as a static library (see +<a class="reference external" href="builtin.html#ref-builtin"><em>Builtin Modules and Custom Interpreters</em></a>).</li> +<li><em>console</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>qt</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>opengl</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>threaded</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>warnings</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>debug</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>dir</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>makefile</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>installs</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>strip</em> – is set if the module should be stripped of unneeded symbols after +installation. It is ignored if either <em>debug</em> or <em>static</em> is set, +or if the platform doesn’t support it.</li> +<li><em>export_all</em> – 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 <em>debug</em> or <em>static</em> is set, or +if the platform doesn’t support it.</li> +<li><em>universal</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>arch</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +</ul> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="sipconfig.ModuleMakefile.finalise"> +<tt class="descname">finalise</tt><big>(</big><big>)</big><a class="headerlink" href="#sipconfig.ModuleMakefile.finalise" title="Permalink to this definition">¶</a></dt> +<dd>This is a reimplementation of <a title="sipconfig.Makefile.finalise" class="reference internal" href="#sipconfig.Makefile.finalise"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.finalise()</span></tt></a>.</dd></dl> + +<dl class="method"> +<dt id="sipconfig.ModuleMakefile.generate_macros_and_rules"> +<tt class="descname">generate_macros_and_rules</tt><big>(</big><em>mfile</em><big>)</big><a class="headerlink" href="#sipconfig.ModuleMakefile.generate_macros_and_rules" title="Permalink to this definition">¶</a></dt> +<dd>This is a reimplementation of +<a title="sipconfig.Makefile.generate_macros_and_rules" class="reference internal" href="#sipconfig.Makefile.generate_macros_and_rules"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.generate_macros_and_rules()</span></tt></a>.</dd></dl> + +<dl class="method"> +<dt id="sipconfig.ModuleMakefile.generate_target_clean"> +<tt class="descname">generate_target_clean</tt><big>(</big><em>mfile</em><big>)</big><a class="headerlink" href="#sipconfig.ModuleMakefile.generate_target_clean" title="Permalink to this definition">¶</a></dt> +<dd>This is a reimplementation of +<a title="sipconfig.Makefile.generate_target_clean" class="reference internal" href="#sipconfig.Makefile.generate_target_clean"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.generate_target_clean()</span></tt></a>.</dd></dl> + +<dl class="method"> +<dt id="sipconfig.ModuleMakefile.generate_target_default"> +<tt class="descname">generate_target_default</tt><big>(</big><em>mfile</em><big>)</big><a class="headerlink" href="#sipconfig.ModuleMakefile.generate_target_default" title="Permalink to this definition">¶</a></dt> +<dd>This is a reimplementation of +<a title="sipconfig.Makefile.generate_target_default" class="reference internal" href="#sipconfig.Makefile.generate_target_default"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.generate_target_default()</span></tt></a>.</dd></dl> + +<dl class="method"> +<dt id="sipconfig.ModuleMakefile.generate_target_install"> +<tt class="descname">generate_target_install</tt><big>(</big><em>mfile</em><big>)</big><a class="headerlink" href="#sipconfig.ModuleMakefile.generate_target_install" title="Permalink to this definition">¶</a></dt> +<dd>This is a reimplementation of +<a title="sipconfig.Makefile.generate_target_install" class="reference internal" href="#sipconfig.Makefile.generate_target_install"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.generate_target_install()</span></tt></a>.</dd></dl> + +<dl class="method"> +<dt id="sipconfig.ModuleMakefile.module_as_lib"> +<tt class="descname">module_as_lib</tt><big>(</big><em>mname</em><big>)</big> → string<a class="headerlink" href="#sipconfig.ModuleMakefile.module_as_lib" title="Permalink to this definition">¶</a></dt> +<dd><p>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.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>mname</em> – the name of the module.</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body">the corresponding library name.</td> +</tr> +</tbody> +</table> +</dd></dl> + +</dd></dl> + +<dl class="class"> +<dt id="sipconfig.ParentMakefile"> +<em class="property">class </em><tt class="descclassname">sipconfig.</tt><tt class="descname">ParentMakefile</tt><a class="headerlink" href="#sipconfig.ParentMakefile" title="Permalink to this definition">¶</a></dt> +<dd><p>This class is derived from <a title="sipconfig.Makefile" class="reference internal" href="#sipconfig.Makefile"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile</span></tt></a>.</p> +<p>This class encapsulates a Makefile that sits above a number of other +Makefiles in sub-directories.</p> +<dl class="method"> +<dt id="sipconfig.ParentMakefile.__init__"> +<tt class="descname">__init__</tt><big>(</big><em>self</em>, <em>configuration</em>, <em>subdirs</em><span class="optional">[</span>, <em>dir=None</em><span class="optional">[</span>, <em>makefile</em><span class="optional">[</span>, <em>="Makefile"</em><span class="optional">[</span>, <em>installs=None</em><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><big>)</big><a class="headerlink" href="#sipconfig.ParentMakefile.__init__" title="Permalink to this definition">¶</a></dt> +<dd><table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><em>configuration</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>subdirs</em> – the sequence of sub-directories.</li> +<li><em>dir</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>makefile</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>installs</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +</ul> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="sipconfig.ParentMakefile.generate_macros_and_rules"> +<tt class="descname">generate_macros_and_rules</tt><big>(</big><em>mfile</em><big>)</big><a class="headerlink" href="#sipconfig.ParentMakefile.generate_macros_and_rules" title="Permalink to this definition">¶</a></dt> +<dd>This is a reimplementation of +<a title="sipconfig.Makefile.generate_macros_and_rules" class="reference internal" href="#sipconfig.Makefile.generate_macros_and_rules"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.generate_macros_and_rules()</span></tt></a>.</dd></dl> + +<dl class="method"> +<dt id="sipconfig.ParentMakefile.generate_target_clean"> +<tt class="descname">generate_target_clean</tt><big>(</big><em>mfile</em><big>)</big><a class="headerlink" href="#sipconfig.ParentMakefile.generate_target_clean" title="Permalink to this definition">¶</a></dt> +<dd>This is a reimplementation of +<a title="sipconfig.Makefile.generate_target_clean" class="reference internal" href="#sipconfig.Makefile.generate_target_clean"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.generate_target_clean()</span></tt></a>.</dd></dl> + +<dl class="method"> +<dt id="sipconfig.ParentMakefile.generate_target_default"> +<tt class="descname">generate_target_default</tt><big>(</big><em>mfile</em><big>)</big><a class="headerlink" href="#sipconfig.ParentMakefile.generate_target_default" title="Permalink to this definition">¶</a></dt> +<dd>This is a reimplementation of +<a title="sipconfig.Makefile.generate_target_default" class="reference internal" href="#sipconfig.Makefile.generate_target_default"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.generate_target_default()</span></tt></a>.</dd></dl> + +<dl class="method"> +<dt id="sipconfig.ParentMakefile.generate_target_install"> +<tt class="descname">generate_target_install</tt><big>(</big><em>mfile</em><big>)</big><a class="headerlink" href="#sipconfig.ParentMakefile.generate_target_install" title="Permalink to this definition">¶</a></dt> +<dd>This is a reimplementation of +<a title="sipconfig.Makefile.generate_target_install" class="reference internal" href="#sipconfig.Makefile.generate_target_install"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.generate_target_install()</span></tt></a>.</dd></dl> + +</dd></dl> + +<dl class="class"> +<dt id="sipconfig.ProgramMakefile"> +<em class="property">class </em><tt class="descclassname">sipconfig.</tt><tt class="descname">ProgramMakefile</tt><a class="headerlink" href="#sipconfig.ProgramMakefile" title="Permalink to this definition">¶</a></dt> +<dd><p>This class is derived from <a title="sipconfig.Makefile" class="reference internal" href="#sipconfig.Makefile"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile</span></tt></a>.</p> +<p>This class encapsulates a Makefile to build an executable program.</p> +<dl class="method"> +<dt id="sipconfig.ProgramMakefile.__init__"> +<tt class="descname">__init__</tt><big>(</big><em>configuration</em><span class="optional">[</span>, <em>build_file=None</em><span class="optional">[</span>, <em>install_dir=None</em><span class="optional">[</span>, <em>console=0</em><span class="optional">[</span>, <em>qt=0</em><span class="optional">[</span>, <em>opengl=0</em><span class="optional">[</span>, <em>python=0</em><span class="optional">[</span>, <em>threaded=0</em><span class="optional">[</span>, <em>warnings=None</em><span class="optional">[</span>, <em>debug=0</em><span class="optional">[</span>, <em>dir=None</em><span class="optional">[</span>, <em>makefile="Makefile"</em><span class="optional">[</span>, <em>installs=None</em><span class="optional">[</span>, <em>universal=None</em><span class="optional">[</span>, <em>arch=None</em><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><big>)</big><a class="headerlink" href="#sipconfig.ProgramMakefile.__init__" title="Permalink to this definition">¶</a></dt> +<dd><table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><em>configuration</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>build_file</em> – the name of the optional build file. Build files are generated +using the <a class="reference external" href="command_line.html#cmdoption-sip-b"><em class="xref">-b</em></a> SIP command line option.</li> +<li><em>install_dir</em> – the name of the directory where the executable program will be +optionally installed.</li> +<li><em>console</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>qt</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>opengl</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>python</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>threaded</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>warnings</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>debug</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>dir</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>makefile</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>installs</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>universal</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>arch</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +</ul> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="sipconfig.ProgramMakefile.build_command"> +<tt class="descname">build_command</tt><big>(</big><em>source</em><big>)</big> → string, string<a class="headerlink" href="#sipconfig.ProgramMakefile.build_command" title="Permalink to this definition">¶</a></dt> +<dd><p>This creates a single command line that will create an executable +program from a single source file.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>source</em> – the name of the source file.</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body">a tuple of the name of the executable that will be created and the +command line.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="sipconfig.ProgramMakefile.finalise"> +<tt class="descname">finalise</tt><big>(</big><big>)</big><a class="headerlink" href="#sipconfig.ProgramMakefile.finalise" title="Permalink to this definition">¶</a></dt> +<dd>This is a reimplementation of <a title="sipconfig.Makefile.finalise" class="reference internal" href="#sipconfig.Makefile.finalise"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.finalise()</span></tt></a>.</dd></dl> + +<dl class="method"> +<dt id="sipconfig.ProgramMakefile.generate_macros_and_rules"> +<tt class="descname">generate_macros_and_rules</tt><big>(</big><em>mfile</em><big>)</big><a class="headerlink" href="#sipconfig.ProgramMakefile.generate_macros_and_rules" title="Permalink to this definition">¶</a></dt> +<dd>This is a reimplementation of +<a title="sipconfig.Makefile.generate_macros_and_rules" class="reference internal" href="#sipconfig.Makefile.generate_macros_and_rules"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.generate_macros_and_rules()</span></tt></a>.</dd></dl> + +<dl class="method"> +<dt id="sipconfig.ProgramMakefile.generate_target_clean"> +<tt class="descname">generate_target_clean</tt><big>(</big><em>mfile</em><big>)</big><a class="headerlink" href="#sipconfig.ProgramMakefile.generate_target_clean" title="Permalink to this definition">¶</a></dt> +<dd>This is a reimplementation of +<a title="sipconfig.Makefile.generate_target_clean" class="reference internal" href="#sipconfig.Makefile.generate_target_clean"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.generate_target_clean()</span></tt></a>.</dd></dl> + +<dl class="method"> +<dt id="sipconfig.ProgramMakefile.generate_target_default"> +<tt class="descname">generate_target_default</tt><big>(</big><em>mfile</em><big>)</big><a class="headerlink" href="#sipconfig.ProgramMakefile.generate_target_default" title="Permalink to this definition">¶</a></dt> +<dd>This is a reimplementation of +<a title="sipconfig.Makefile.generate_target_default" class="reference internal" href="#sipconfig.Makefile.generate_target_default"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.generate_target_default()</span></tt></a>.</dd></dl> + +<dl class="method"> +<dt id="sipconfig.ProgramMakefile.generate_target_install"> +<tt class="descname">generate_target_install</tt><big>(</big><em>mfile</em><big>)</big><a class="headerlink" href="#sipconfig.ProgramMakefile.generate_target_install" title="Permalink to this definition">¶</a></dt> +<dd>This is a reimplementation of +<a title="sipconfig.Makefile.generate_target_install" class="reference internal" href="#sipconfig.Makefile.generate_target_install"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.generate_target_install()</span></tt></a>.</dd></dl> + +</dd></dl> + +<dl class="class"> +<dt id="sipconfig.PythonModuleMakefile"> +<em class="property">class </em><tt class="descclassname">sipconfig.</tt><tt class="descname">PythonModuleMakefile</tt><a class="headerlink" href="#sipconfig.PythonModuleMakefile" title="Permalink to this definition">¶</a></dt> +<dd><p>This class is derived from <a title="sipconfig.Makefile" class="reference internal" href="#sipconfig.Makefile"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile</span></tt></a>.</p> +<p>This class encapsulates a Makefile that installs a pure Python module.</p> +<dl class="method"> +<dt id="sipconfig.PythonModuleMakefile.__init__"> +<tt class="descname">__init__</tt><big>(</big><em>self</em>, <em>configuration</em>, <em>dstdir</em><span class="optional">[</span>, <em>srcdir=None</em><span class="optional">[</span>, <em>dir=None</em><span class="optional">[</span>, <em>makefile="Makefile"</em><span class="optional">[</span>, <em>installs=None</em><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><big>)</big><a class="headerlink" href="#sipconfig.PythonModuleMakefile.__init__" title="Permalink to this definition">¶</a></dt> +<dd><table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><em>configuration</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>dstdir</em> – the name of the directory in which the module’s Python code will be +installed.</li> +<li><em>srcdir</em> – the name of the directory (relative to <em>dir</em>) containing the +module’s Python code. It defaults to the same directory.</li> +<li><em>dir</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>makefile</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>installs</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +</ul> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="sipconfig.PythonModuleMakefile.generate_macros_and_rules"> +<tt class="descname">generate_macros_and_rules</tt><big>(</big><em>mfile</em><big>)</big><a class="headerlink" href="#sipconfig.PythonModuleMakefile.generate_macros_and_rules" title="Permalink to this definition">¶</a></dt> +<dd>This is a reimplementation of +<a title="sipconfig.Makefile.generate_macros_and_rules" class="reference internal" href="#sipconfig.Makefile.generate_macros_and_rules"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.generate_macros_and_rules()</span></tt></a>.</dd></dl> + +<dl class="method"> +<dt id="sipconfig.PythonModuleMakefile.generate_target_install"> +<tt class="descname">generate_target_install</tt><big>(</big><em>mfile</em><big>)</big><a class="headerlink" href="#sipconfig.PythonModuleMakefile.generate_target_install" title="Permalink to this definition">¶</a></dt> +<dd>This is a reimplementation of +<a title="sipconfig.Makefile.generate_target_install" class="reference internal" href="#sipconfig.Makefile.generate_target_install"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.generate_target_install()</span></tt></a>.</dd></dl> + +</dd></dl> + +<dl class="class"> +<dt id="sipconfig.SIPModuleMakefile"> +<em class="property">class </em><tt class="descclassname">sipconfig.</tt><tt class="descname">SIPModuleMakefile</tt><a class="headerlink" href="#sipconfig.SIPModuleMakefile" title="Permalink to this definition">¶</a></dt> +<dd><p>This class is derived from <a title="sipconfig.ModuleMakefile" class="reference internal" href="#sipconfig.ModuleMakefile"><tt class="xref docutils literal"><span class="pre">sipconfig.ModuleMakefile</span></tt></a>.</p> +<p>This class encapsulates a Makefile to build a SIP generated Python +extension module.</p> +<dl class="method"> +<dt id="sipconfig.SIPModuleMakefile.__init__"> +<tt class="descname">__init__</tt><big>(</big><em>self</em>, <em>configuration</em>, <em>build_file</em><span class="optional">[</span>, <em>install_dir=None</em><span class="optional">[</span>, <em>static=0</em><span class="optional">[</span>, <em>console=0</em><span class="optional">[</span>, <em>opengl=0</em><span class="optional">[</span>, <em>threaded=0</em><span class="optional">[</span>, <em>warnings=None</em><span class="optional">[</span>, <em>debug=0</em><span class="optional">[</span>, <em>dir=None</em><span class="optional">[</span>, <em>makefile="Makefile"</em><span class="optional">[</span>, <em>installs=None</em><span class="optional">[</span>, <em>strip=1</em><span class="optional">[</span>, <em>export_all=0</em><span class="optional">[</span>, <em>universal=None</em><span class="optional">[</span>, <em>arch=None</em><span class="optional">[</span>, <em>prot_is_public=0</em><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><big>)</big><a class="headerlink" href="#sipconfig.SIPModuleMakefile.__init__" title="Permalink to this definition">¶</a></dt> +<dd><table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><em>configuration</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>build_file</em> – see <a title="sipconfig.ModuleMakefile.__init__" class="reference internal" href="#sipconfig.ModuleMakefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.ModuleMakefile.__init__()</span></tt></a>.</li> +<li><em>install_dir</em> – see <a title="sipconfig.ModuleMakefile.__init__" class="reference internal" href="#sipconfig.ModuleMakefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.ModuleMakefile.__init__()</span></tt></a>.</li> +<li><em>static</em> – see <a title="sipconfig.ModuleMakefile.__init__" class="reference internal" href="#sipconfig.ModuleMakefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.ModuleMakefile.__init__()</span></tt></a>.</li> +<li><em>console</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>qt</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>opengl</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>threaded</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>warnings</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>debug</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>dir</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>makefile</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>installs</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>strip</em> – see <a title="sipconfig.ModuleMakefile.__init__" class="reference internal" href="#sipconfig.ModuleMakefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.ModuleMakefile.__init__()</span></tt></a>.</li> +<li><em>export_all</em> – see <a title="sipconfig.ModuleMakefile.__init__" class="reference internal" href="#sipconfig.ModuleMakefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.ModuleMakefile.__init__()</span></tt></a>.</li> +<li><em>universal</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>arch</em> – see <a title="sipconfig.Makefile.__init__" class="reference internal" href="#sipconfig.Makefile.__init__"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.__init__()</span></tt></a>.</li> +<li><em>prot_is_public</em> – is set if <tt class="docutils literal"><span class="pre">protected</span></tt> should be redefined as <tt class="docutils literal"><span class="pre">public</span></tt> when +compiling the generated module.</li> +</ul> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="sipconfig.SIPModuleMakefile.finalise"> +<tt class="descname">finalise</tt><big>(</big><big>)</big><a class="headerlink" href="#sipconfig.SIPModuleMakefile.finalise" title="Permalink to this definition">¶</a></dt> +<dd>This is a reimplementation of <a title="sipconfig.Makefile.finalise" class="reference internal" href="#sipconfig.Makefile.finalise"><tt class="xref docutils literal"><span class="pre">sipconfig.Makefile.finalise()</span></tt></a>.</dd></dl> + +</dd></dl> + +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h4>Previous topic</h4> + <p class="topless"><a href="python_api.html" + title="previous chapter">Python API for Applications</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="distutils.html" + title="next chapter">Building Your Extension with distutils</a></p> + <div id="searchbox" style="display: none"> + <h3>Quick search</h3> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" size="18" /> + <input type="submit" value="Go" /> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </form> + <p class="searchtip" style="font-size: 90%"> + Enter search terms or a module, class or function name. + </p> + </div> + <script type="text/javascript">$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="modindex.html" title="Global Module Index" + >modules</a> |</li> + <li class="right" > + <a href="distutils.html" title="Building Your Extension with distutils" + >next</a> |</li> + <li class="right" > + <a href="python_api.html" title="Python API for Applications" + >previous</a> |</li> + <li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2010 Riverbank Computing Limited. + Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.4. + </div> + </body> +</html>
\ No newline at end of file diff --git a/doc/html/builtin.html b/doc/html/builtin.html new file mode 100644 index 0000000..e8ba2ec --- /dev/null +++ b/doc/html/builtin.html @@ -0,0 +1,138 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + + <title>Builtin Modules and Custom Interpreters — SIP 4.10.5 Reference Guide</title> + <link rel="stylesheet" href="_static/default.css" type="text/css" /> + <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '#', + VERSION: '4.10.5', + COLLAPSE_MODINDEX: false, + FILE_SUFFIX: '.html', + HAS_SOURCE: true + }; + </script> + <script type="text/javascript" src="_static/jquery.js"></script> + <script type="text/javascript" src="_static/doctools.js"></script> + <link rel="top" title="SIP 4.10.5 Reference Guide" href="index.html" /> + <link rel="prev" title="Building Your Extension with distutils" href="distutils.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="modindex.html" title="Global Module Index" + accesskey="M">modules</a> |</li> + <li class="right" > + <a href="distutils.html" title="Building Your Extension with distutils" + accesskey="P">previous</a> |</li> + <li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="builtin-modules-and-custom-interpreters"> +<span id="ref-builtin"></span><h1>Builtin Modules and Custom Interpreters<a class="headerlink" href="#builtin-modules-and-custom-interpreters" title="Permalink to this headline">¶</a></h1> +<p>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.</p> +<p>To build the SIP module as a static library you must pass the <tt class="docutils literal"><span class="pre">-k</span></tt> command +line option to <tt class="docutils literal"><span class="pre">configure.py</span></tt>. 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.)</p> +<p>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 <tt class="docutils literal"><span class="pre">static</span></tt> argument +of the <tt class="docutils literal"><span class="pre">__init__()</span></tt> method of the <a title="sipconfig.ModuleMakefile" class="reference external" href="build_system.html#sipconfig.ModuleMakefile"><tt class="xref docutils literal"><span class="pre">sipconfig.ModuleMakefile</span></tt></a> 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 <tt class="docutils literal"><span class="pre">configure.py</span></tt> handles +it.</p> +<p>The next stage is to create a custom stub and a Makefile. The SIP distribution +contains a directory called <tt class="docutils literal"><span class="pre">custom</span></tt> 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 <tt class="docutils literal"><span class="pre">custom</span></tt> directory may +not be installed on your system.</p> +<p>The <tt class="docutils literal"><span class="pre">custom</span></tt> directory contains the following files. They are provided as +examples - each needs to be modified according to your particular +requirements.</p> +<blockquote> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">mkcustom.py</span></tt> 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.</li> +<li><tt class="docutils literal"><span class="pre">custom.c</span></tt> 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 <tt class="docutils literal"><span class="pre">python.exe</span></tt>). Comments in the file describe how it should be +modified.</li> +<li><tt class="docutils literal"><span class="pre">customw.c</span></tt> is a stub for a custom GUI interpreter on Windows (i.e. +like <tt class="docutils literal"><span class="pre">pythonw.exe</span></tt>). Comments in the file describe how it should be +modified.</li> +</ul> +</blockquote> +<p>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 +<a class="reference external" href="http://www.riverbankcomputing.com/software/vendorid/">VendorID</a> package.</p> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h4>Previous topic</h4> + <p class="topless"><a href="distutils.html" + title="previous chapter">Building Your Extension with distutils</a></p> + <div id="searchbox" style="display: none"> + <h3>Quick search</h3> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" size="18" /> + <input type="submit" value="Go" /> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </form> + <p class="searchtip" style="font-size: 90%"> + Enter search terms or a module, class or function name. + </p> + </div> + <script type="text/javascript">$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="modindex.html" title="Global Module Index" + >modules</a> |</li> + <li class="right" > + <a href="distutils.html" title="Building Your Extension with distutils" + >previous</a> |</li> + <li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2010 Riverbank Computing Limited. + Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.4. + </div> + </body> +</html>
\ No newline at end of file diff --git a/doc/html/c_api.html b/doc/html/c_api.html new file mode 100644 index 0000000..b761f8a --- /dev/null +++ b/doc/html/c_api.html @@ -0,0 +1,2166 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + + <title>C API for Handwritten Code — SIP 4.10.5 Reference Guide</title> + <link rel="stylesheet" href="_static/default.css" type="text/css" /> + <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '#', + VERSION: '4.10.5', + COLLAPSE_MODINDEX: false, + FILE_SUFFIX: '.html', + HAS_SOURCE: true + }; + </script> + <script type="text/javascript" src="_static/jquery.js"></script> + <script type="text/javascript" src="_static/doctools.js"></script> + <link rel="top" title="SIP 4.10.5 Reference Guide" href="index.html" /> + <link rel="next" title="Using the C API when Embedding" href="embedding.html" /> + <link rel="prev" title="Annotations" href="annotations.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="modindex.html" title="Global Module Index" + accesskey="M">modules</a> |</li> + <li class="right" > + <a href="embedding.html" title="Using the C API when Embedding" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="annotations.html" title="Annotations" + accesskey="P">previous</a> |</li> + <li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="c-api-for-handwritten-code"> +<span id="ref-c-api"></span><h1>C API for Handwritten Code<a class="headerlink" href="#c-api-for-handwritten-code" title="Permalink to this headline">¶</a></h1> +<p>In this section we describe the API that can be used by handwritten code in +specification files.</p> +<dl class="cmacro"> +<dt id="SIP_API_MAJOR_NR"> +<tt class="descname">SIP_API_MAJOR_NR</tt><a class="headerlink" href="#SIP_API_MAJOR_NR" title="Permalink to this definition">¶</a></dt> +<dd>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.</dd></dl> + +<dl class="cmacro"> +<dt id="SIP_API_MINOR_NR"> +<tt class="descname">SIP_API_MINOR_NR</tt><a class="headerlink" href="#SIP_API_MINOR_NR" title="Permalink to this definition">¶</a></dt> +<dd>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.</dd></dl> + +<dl class="cmacro"> +<dt id="SIP_BLOCK_THREADS"> +<tt class="descname">SIP_BLOCK_THREADS</tt><a class="headerlink" href="#SIP_BLOCK_THREADS" title="Permalink to this definition">¶</a></dt> +<dd>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 +<a title="SIP_UNBLOCK_THREADS" class="reference internal" href="#SIP_UNBLOCK_THREADS"><tt class="xref docutils literal"><span class="pre">SIP_UNBLOCK_THREADS</span></tt></a> at the same lexical scope.</dd></dl> + +<dl class="cmacro"> +<dt id="SIP_NO_CONVERTORS"> +<tt class="descname">SIP_NO_CONVERTORS</tt><a class="headerlink" href="#SIP_NO_CONVERTORS" title="Permalink to this definition">¶</a></dt> +<dd>This is a flag used by various type convertors that suppresses the use of a +type’s <a class="reference external" href="directives.html#directive-%ConvertToTypeCode"><tt class="xref docutils literal"><span class="pre">%ConvertToTypeCode</span></tt></a>.</dd></dl> + +<dl class="cmacro"> +<dt id="SIP_NOT_NONE"> +<tt class="descname">SIP_NOT_NONE</tt><a class="headerlink" href="#SIP_NOT_NONE" title="Permalink to this definition">¶</a></dt> +<dd>This is a flag used by various type convertors that causes the conversion +to fail if the Python object being converted is <tt class="docutils literal"><span class="pre">Py_None</span></tt>.</dd></dl> + +<dl class="cmacro"> +<dt id="SIP_PROTECTED_IS_PUBLIC"> +<tt class="descname">SIP_PROTECTED_IS_PUBLIC</tt><a class="headerlink" href="#SIP_PROTECTED_IS_PUBLIC" title="Permalink to this definition">¶</a></dt> +<dd><p> +<span class="versionmodified">New in version 4.10.</span></p> +<p>This is a C preprocessor macro that is set automatically by the build +system to specify that the generated code is being compiled with +<tt class="docutils literal"><span class="pre">protected</span></tt> redefined as <tt class="docutils literal"><span class="pre">public</span></tt>. This allows handwritten code to +determine if the generated helper functions for accessing protected C++ +functions are available (see <a class="reference external" href="directives.html#directive-%MethodCode"><tt class="xref docutils literal"><span class="pre">%MethodCode</span></tt></a>).</p> +</dd></dl> + +<dl class="cmacro"> +<dt id="SIP_SSIZE_T"> +<tt class="descname">SIP_SSIZE_T</tt><a class="headerlink" href="#SIP_SSIZE_T" title="Permalink to this definition">¶</a></dt> +<dd>This is a C preprocessor macro that is defined as <tt class="docutils literal"><span class="pre">Py_ssize_t</span></tt> for Python +v2.5 and later, and as <tt class="docutils literal"><span class="pre">int</span></tt> for earlier versions of Python. It makes it +easier to write PEP 353 compliant handwritten code.</dd></dl> + +<dl class="cmacro"> +<dt id="SIP_UNBLOCK_THREADS"> +<tt class="descname">SIP_UNBLOCK_THREADS</tt><a class="headerlink" href="#SIP_UNBLOCK_THREADS" title="Permalink to this definition">¶</a></dt> +<dd>This is a C preprocessor macro that will restore the Python Global +Interpreter Lock (GIL) to the state it was prior to the corresponding +<a title="SIP_BLOCK_THREADS" class="reference internal" href="#SIP_BLOCK_THREADS"><tt class="xref docutils literal"><span class="pre">SIP_BLOCK_THREADS</span></tt></a>.</dd></dl> + +<dl class="cmacro"> +<dt id="SIP_VERSION"> +<tt class="descname">SIP_VERSION</tt><a class="headerlink" href="#SIP_VERSION" title="Permalink to this definition">¶</a></dt> +<dd>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 +<tt class="docutils literal"><span class="pre">0x040000</span></tt>).</dd></dl> + +<dl class="cmacro"> +<dt id="SIP_VERSION_STR"> +<tt class="descname">SIP_VERSION_STR</tt><a class="headerlink" href="#SIP_VERSION_STR" title="Permalink to this definition">¶</a></dt> +<dd>This is a C preprocessor symbol that defines the SIP version number +represented as a string. For development snapshots it will start with +<tt class="docutils literal"><span class="pre">snapshot-</span></tt>.</dd></dl> + +<dl class="cfunction"> +<dt id="sipBadCallableArg"> +sipErrorState <tt class="descname">sipBadCallableArg</tt><big>(</big>int<em> arg_nr</em>, PyObject<em> *arg</em><big>)</big><a class="headerlink" href="#sipBadCallableArg" title="Permalink to this definition">¶</a></dt> +<dd><p> +<span class="versionmodified">New in version 4.10.</span></p> +<p>This is called from <a class="reference external" href="directives.html#directive-%MethodCode"><tt class="xref docutils literal"><span class="pre">%MethodCode</span></tt></a> 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 +<a class="reference external" href="directives.html#directive-%MethodCode"><tt class="xref docutils literal"><span class="pre">%MethodCode</span></tt></a> does additional type checking of the supplied +arguments.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><em>arg_nr</em> – the number of the argument. Arguments are numbered from 0 but are +numbered from 1 in the detail of the exception.</li> +<li><em>arg</em> – the argument.</li> +</ul> +</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the value that should be assigned to <tt class="docutils literal"><span class="pre">sipError</span></tt>.</p> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipBadCatcherResult"> +void <tt class="descname">sipBadCatcherResult</tt><big>(</big>PyObject<em> *method</em><big>)</big><a class="headerlink" href="#sipBadCatcherResult" title="Permalink to this definition">¶</a></dt> +<dd><p>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 <a class="reference external" href="directives.html#directive-%VirtualCatcherCode"><tt class="xref docutils literal"><span class="pre">%VirtualCatcherCode</span></tt></a> +directive.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>method</em> – the Python method and would normally be the supplied <tt class="docutils literal"><span class="pre">sipMethod</span></tt>.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipBadLengthForSlice"> +void <tt class="descname">sipBadLengthForSlice</tt><big>(</big><a title="SIP_SSIZE_T" class="reference internal" href="#SIP_SSIZE_T">SIP_SSIZE_T</a><em> seqlen</em>, <a title="SIP_SSIZE_T" class="reference internal" href="#SIP_SSIZE_T">SIP_SSIZE_T</a><em> slicelen</em><big>)</big><a class="headerlink" href="#sipBadLengthForSlice" title="Permalink to this definition">¶</a></dt> +<dd><p>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 <tt class="xref docutils literal"><span class="pre">__setitem__()</span></tt> methods.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><em>seqlen</em> – the length of the sequence.</li> +<li><em>slicelen</em> – the length of the slice.</li> +</ul> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipBuildResult"> +PyObject *<tt class="descname">sipBuildResult</tt><big>(</big>int<em> *iserr</em>, const char<em> *format</em>, ...<big>)</big><a class="headerlink" href="#sipBuildResult" title="Permalink to this definition">¶</a></dt> +<dd><p>This creates a Python object based on a format string and associated +values in a similar way to the Python <tt class="xref docutils literal"><span class="pre">Py_BuildValue()</span></tt> function.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><em>iserr</em> – if this is not <tt class="docutils literal"><span class="pre">NULL</span></tt> then the location it points to is set to a +non-zero value.</li> +<li><em>format</em> – the string of format characters.</li> +</ul> +</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">If there was an error then <tt class="docutils literal"><span class="pre">NULL</span></tt> is returned and a Python exception +is raised.</p> +</td> +</tr> +</tbody> +</table> +<p>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.</p> +<p>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.</p> +<dl class="docutils"> +<dt><tt class="docutils literal"><span class="pre">a</span></tt> (string) [char]</dt> +<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">char</span></tt> to a Python v2 or v3 string object.</dd> +<dt><tt class="docutils literal"><span class="pre">b</span></tt> (boolean) [int]</dt> +<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">int</span></tt> to a Python boolean.</dd> +<dt><tt class="docutils literal"><span class="pre">c</span></tt> (string/bytes) [char]</dt> +<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">char</span></tt> to a Python v2 string object or a Python v3 +bytes object.</dd> +<dt><tt class="docutils literal"><span class="pre">d</span></tt> (float) [double]</dt> +<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">double</span></tt> to a Python floating point number.</dd> +<dt><tt class="docutils literal"><span class="pre">e</span></tt> (integer) [enum]</dt> +<dd>Convert an anonymous C/C++ <tt class="docutils literal"><span class="pre">enum</span></tt> to a Python integer.</dd> +<dt><tt class="docutils literal"><span class="pre">f</span></tt> (float) [float]</dt> +<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">float</span></tt> to a Python floating point number.</dd> +<dt><tt class="docutils literal"><span class="pre">g</span></tt> (string/bytes) [char *, <a title="SIP_SSIZE_T" class="reference internal" href="#SIP_SSIZE_T"><tt class="xref docutils literal"><span class="pre">SIP_SSIZE_T</span></tt></a>]</dt> +<dd>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 <tt class="docutils literal"><span class="pre">NULL</span></tt> then the +length is ignored and the result is <tt class="docutils literal"><span class="pre">Py_None</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">h</span></tt> (integer) [short]</dt> +<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">short</span></tt> to a Python integer.</dd> +<dt><tt class="docutils literal"><span class="pre">i</span></tt> (integer) [int]</dt> +<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">int</span></tt> to a Python integer.</dd> +<dt><tt class="docutils literal"><span class="pre">l</span></tt> (long) [long]</dt> +<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">long</span></tt> to a Python integer.</dd> +<dt><tt class="docutils literal"><span class="pre">m</span></tt> (long) [unsigned long]</dt> +<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">long</span></tt> to a Python long.</dd> +<dt><tt class="docutils literal"><span class="pre">n</span></tt> (long) [long long]</dt> +<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">long</span> <span class="pre">long</span></tt> to a Python long.</dd> +<dt><tt class="docutils literal"><span class="pre">o</span></tt> (long) [unsigned long long]</dt> +<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">long</span> <span class="pre">long</span></tt> to a Python long.</dd> +<dt><tt class="docutils literal"><span class="pre">r</span></tt> (wrapped instance) [<em>type</em> *, <a title="SIP_SSIZE_T" class="reference internal" href="#SIP_SSIZE_T"><tt class="xref docutils literal"><span class="pre">SIP_SSIZE_T</span></tt></a>, const <tt class="xref docutils literal"><span class="pre">sipTypeDef</span></tt> *]</dt> +<dd>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.</dd> +<dt><tt class="docutils literal"><span class="pre">s</span></tt> (string/bytes) [char *]</dt> +<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">'\0'</span></tt> terminated string to a Python v2 string object +or a Python v3 bytes object. If the string pointer is <tt class="docutils literal"><span class="pre">NULL</span></tt> then +the result is <tt class="docutils literal"><span class="pre">Py_None</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">t</span></tt> (long) [unsigned short]</dt> +<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">short</span></tt> to a Python long.</dd> +<dt><tt class="docutils literal"><span class="pre">u</span></tt> (long) [unsigned int]</dt> +<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">int</span></tt> to a Python long.</dd> +<dt><tt class="docutils literal"><span class="pre">w</span></tt> (unicode/string) [wchar_t]</dt> +<dd>Convert a C/C++ wide character to a Python v2 unicode object or a +Python v3 string object.</dd> +<dt><tt class="docutils literal"><span class="pre">x</span></tt> (unicode/string) [wchar_t *]</dt> +<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">L'\0'</span></tt> terminated wide character string to a Python +v2 unicode object or a Python v3 string object. If the string pointer +is <tt class="docutils literal"><span class="pre">NULL</span></tt> then the result is <tt class="docutils literal"><span class="pre">Py_None</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">A</span></tt> (string) [char *]</dt> +<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">'\0'</span></tt> terminated string to a Python v2 or v3 string +object. If the string pointer is <tt class="docutils literal"><span class="pre">NULL</span></tt> then the result is +<tt class="docutils literal"><span class="pre">Py_None</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">B</span></tt> (wrapped instance) [<em>type</em> *, <a title="sipWrapperType" class="reference internal" href="#sipWrapperType"><tt class="xref docutils literal"><span class="pre">sipWrapperType</span></tt></a> *, PyObject *]</dt> +<dd><p class="first">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 <tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt> argument. If it is <tt class="docutils literal"><span class="pre">NULL</span></tt> and the instance has +already been wrapped then the ownership is unchanged. If it is +<tt class="docutils literal"><span class="pre">NULL</span></tt> or <tt class="docutils literal"><span class="pre">Py_None</span></tt> then ownership will be with Python. Otherwise +ownership will be with C/C++ and the instance associated with the +<tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt> argument. The Python class is influenced by any +applicable <a class="reference external" href="directives.html#directive-%ConvertToSubClassCode"><tt class="xref docutils literal"><span class="pre">%ConvertToSubClassCode</span></tt></a> code.</p> +<div class="last admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">This is deprecated from SIP v4.8. Instead you should use <tt class="docutils literal"><span class="pre">N</span></tt>.</p> +</div> +</dd> +<dt><tt class="docutils literal"><span class="pre">C</span></tt> (wrapped instance) [<em>type</em> *, <a title="sipWrapperType" class="reference internal" href="#sipWrapperType"><tt class="xref docutils literal"><span class="pre">sipWrapperType</span></tt></a> *, PyObject *]</dt> +<dd><p class="first">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 <tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt> argument. If it is <tt class="docutils literal"><span class="pre">NULL</span></tt> and the instance has +already been wrapped then the ownership is unchanged. If it is +<tt class="docutils literal"><span class="pre">NULL</span></tt> and the instance is newly wrapped then ownership will be with +C/C++. If it is <tt class="docutils literal"><span class="pre">Py_None</span></tt> then ownership is transferred to Python +via a call to <a title="sipTransferBack" class="reference internal" href="#sipTransferBack"><tt class="xref docutils literal"><span class="pre">sipTransferBack()</span></tt></a>. Otherwise ownership is +transferred to C/C++ and the instance associated with the +<tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt> argument via a call to <a title="sipTransferTo" class="reference internal" href="#sipTransferTo"><tt class="xref docutils literal"><span class="pre">sipTransferTo()</span></tt></a>. The +Python class is influenced by any applicable +<a class="reference external" href="directives.html#directive-%ConvertToSubClassCode"><tt class="xref docutils literal"><span class="pre">%ConvertToSubClassCode</span></tt></a> code.</p> +<div class="last admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">This is deprecated from SIP v4.8. Instead you should use <tt class="docutils literal"><span class="pre">D</span></tt>.</p> +</div> +</dd> +<dt><tt class="docutils literal"><span class="pre">D</span></tt> (wrapped instance) [<em>type</em> *, const <tt class="xref docutils literal"><span class="pre">sipTypeDef</span></tt> *, PyObject *]</dt> +<dd>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 <tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt> argument. If it is <tt class="docutils literal"><span class="pre">NULL</span></tt> and the +instance has already been wrapped then the ownership is unchanged. If +it is <tt class="docutils literal"><span class="pre">NULL</span></tt> and the instance is newly wrapped then ownership will be +with C/C++. If it is <tt class="docutils literal"><span class="pre">Py_None</span></tt> then ownership is transferred to +Python via a call to <a title="sipTransferBack" class="reference internal" href="#sipTransferBack"><tt class="xref docutils literal"><span class="pre">sipTransferBack()</span></tt></a>. Otherwise ownership +is transferred to C/C++ and the instance associated with the +<tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt> argument via a call to <a title="sipTransferTo" class="reference internal" href="#sipTransferTo"><tt class="xref docutils literal"><span class="pre">sipTransferTo()</span></tt></a>. The +Python class is influenced by any applicable +<a class="reference external" href="directives.html#directive-%ConvertToSubClassCode"><tt class="xref docutils literal"><span class="pre">%ConvertToSubClassCode</span></tt></a> code.</dd> +<dt><tt class="docutils literal"><span class="pre">E</span></tt> (wrapped enum) [enum, PyTypeObject *]</dt> +<dd><p class="first">Convert a named C/C++ <tt class="docutils literal"><span class="pre">enum</span></tt> to an instance of the corresponding +Python named enum type.</p> +<div class="last admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">This is deprecated from SIP v4.8. Instead you should use <tt class="docutils literal"><span class="pre">F</span></tt>.</p> +</div> +</dd> +<dt><tt class="docutils literal"><span class="pre">F</span></tt> (wrapped enum) [enum, <tt class="xref docutils literal"><span class="pre">sipTypeDef</span></tt> *]</dt> +<dd>Convert a named C/C++ <tt class="docutils literal"><span class="pre">enum</span></tt> to an instance of the corresponding +Python named enum type.</dd> +<dt><tt class="docutils literal"><span class="pre">G</span></tt> (unicode) [wchar_t *, <a title="SIP_SSIZE_T" class="reference internal" href="#SIP_SSIZE_T"><tt class="xref docutils literal"><span class="pre">SIP_SSIZE_T</span></tt></a>]</dt> +<dd>Convert a C/C++ wide character array and its length to a Python unicode +object. If the array is <tt class="docutils literal"><span class="pre">NULL</span></tt> then the length is ignored and the +result is <tt class="docutils literal"><span class="pre">Py_None</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">N</span></tt> (wrapped instance) [<em>type</em> *, <tt class="xref docutils literal"><span class="pre">sipTypeDef</span></tt> *, PyObject *]</dt> +<dd>Convert a new C structure, C++ class or mapped type instance to a +Python object. Ownership of the instance is determined by the +<tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt> argument. If it is <tt class="docutils literal"><span class="pre">NULL</span></tt> and the instance has +already been wrapped then the ownership is unchanged. If it is +<tt class="docutils literal"><span class="pre">NULL</span></tt> or <tt class="docutils literal"><span class="pre">Py_None</span></tt> then ownership will be with Python. Otherwise +ownership will be with C/C++ and the instance associated with the +<tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt> argument. The Python class is influenced by any +applicable <a class="reference external" href="directives.html#directive-%ConvertToSubClassCode"><tt class="xref docutils literal"><span class="pre">%ConvertToSubClassCode</span></tt></a> code.</dd> +<dt><tt class="docutils literal"><span class="pre">R</span></tt> (object) [PyObject *]</dt> +<dd>The result is value passed without any conversions. The reference +count is unaffected, i.e. a reference is taken.</dd> +<dt><tt class="docutils literal"><span class="pre">S</span></tt> (object) [PyObject *]</dt> +<dd>The result is value passed without any conversions. The reference +count is incremented.</dd> +<dt><tt class="docutils literal"><span class="pre">V</span></tt> (sip.voidptr) [void *]</dt> +<dd>Convert a C/C++ <tt class="docutils literal"><span class="pre">void</span> <span class="pre">*</span></tt> Python <a title="sip.voidptr" class="reference external" href="python_api.html#sip.voidptr"><tt class="xref docutils literal"><span class="pre">sip.voidptr</span></tt></a> object.</dd> +</dl> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipCallMethod"> +PyObject *<tt class="descname">sipCallMethod</tt><big>(</big>int<em> *iserr</em>, PyObject<em> *method</em>, const char<em> *format</em>, ...<big>)</big><a class="headerlink" href="#sipCallMethod" title="Permalink to this definition">¶</a></dt> +<dd><p>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 +<tt class="xref docutils literal"><span class="pre">PyObject_CallObject()</span></tt> function.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><em>iserr</em> – if this is not <tt class="docutils literal"><span class="pre">NULL</span></tt> then the location it points to is set to a +non-zero value if there was an error.</li> +<li><em>method</em> – the Python bound method to call.</li> +<li><em>format</em> – the string of format characters (see <a title="sipBuildResult" class="reference internal" href="#sipBuildResult"><tt class="xref docutils literal"><span class="pre">sipBuildResult()</span></tt></a>).</li> +</ul> +</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">If there was an error then <tt class="docutils literal"><span class="pre">NULL</span></tt> is returned and a Python exception +is raised.</p> +</td> +</tr> +</tbody> +</table> +<p>It is normally called by handwritten code specified with the +<a class="reference external" href="directives.html#directive-%VirtualCatcherCode"><tt class="xref docutils literal"><span class="pre">%VirtualCatcherCode</span></tt></a> directive with method being the supplied +<tt class="docutils literal"><span class="pre">sipMethod</span></tt>.</p> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipCanConvertToEnum"> +int <tt class="descname">sipCanConvertToEnum</tt><big>(</big>PyObject<em> *obj</em>, const sipTypeDef<em> *td</em><big>)</big><a class="headerlink" href="#sipCanConvertToEnum" title="Permalink to this definition">¶</a></dt> +<dd><p>This checks if a Python object can be converted to a named enum.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><em>obj</em> – the Python object.</li> +<li><em>td</em> – the enum’s <a class="reference internal" href="#ref-type-structures"><em>generated type structure</em></a>.</li> +</ul> +</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">a non-zero value if the object can be converted.</p> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipCanConvertToInstance"> +int <tt class="descname">sipCanConvertToInstance</tt><big>(</big>PyObject<em> *obj</em>, <a title="sipWrapperType" class="reference internal" href="#sipWrapperType">sipWrapperType</a><em> *type</em>, int<em> flags</em><big>)</big><a class="headerlink" href="#sipCanConvertToInstance" title="Permalink to this definition">¶</a></dt> +<dd><p>This checks if a Python object can be converted to an instance of a C +structure or C++ class.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><em>obj</em> – the Python object.</li> +<li><em>type</em> – the C/C++ type’s <a class="reference internal" href="#ref-type-objects"><em>generated type object</em></a>.</li> +<li><em>flags</em> – any combination of the <a title="SIP_NOT_NONE" class="reference internal" href="#SIP_NOT_NONE"><tt class="xref docutils literal"><span class="pre">SIP_NOT_NONE</span></tt></a> and +<a title="SIP_NO_CONVERTORS" class="reference internal" href="#SIP_NO_CONVERTORS"><tt class="xref docutils literal"><span class="pre">SIP_NO_CONVERTORS</span></tt></a> flags.</li> +</ul> +</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">a non-zero value if the object can be converted.</p> +</td> +</tr> +</tbody> +</table> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">This is deprecated from SIP v4.8. Instead you should use +<a title="sipCanConvertToType" class="reference internal" href="#sipCanConvertToType"><tt class="xref docutils literal"><span class="pre">sipCanConvertToType()</span></tt></a>.</p> +</div> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipCanConvertToMappedType"> +int <tt class="descname">sipCanConvertToMappedType</tt><big>(</big>PyObject<em> *obj</em>, const sipMappedType<em> *mt</em>, int<em> flags</em><big>)</big><a class="headerlink" href="#sipCanConvertToMappedType" title="Permalink to this definition">¶</a></dt> +<dd><p>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.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><em>obj</em> – the Python object.</li> +<li><em>mt</em> – the opaque structure returned by <a title="sipFindMappedType" class="reference internal" href="#sipFindMappedType"><tt class="xref docutils literal"><span class="pre">sipFindMappedType()</span></tt></a>.</li> +<li><em>flags</em> – this may be the <a title="SIP_NOT_NONE" class="reference internal" href="#SIP_NOT_NONE"><tt class="xref docutils literal"><span class="pre">SIP_NOT_NONE</span></tt></a> flag.</li> +</ul> +</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">a non-zero value if the object can be converted.</p> +</td> +</tr> +</tbody> +</table> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">This is deprecated from SIP v4.8. Instead you should use +<a title="sipCanConvertToType" class="reference internal" href="#sipCanConvertToType"><tt class="xref docutils literal"><span class="pre">sipCanConvertToType()</span></tt></a>.</p> +</div> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipCanConvertToType"> +int <tt class="descname">sipCanConvertToType</tt><big>(</big>PyObject<em> *obj</em>, const sipTypeDef<em> *td</em>, int<em> flags</em><big>)</big><a class="headerlink" href="#sipCanConvertToType" title="Permalink to this definition">¶</a></dt> +<dd><p>This checks if a Python object can be converted to an instance of a C +structure, C++ class or mapped type.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><em>obj</em> – the Python object.</li> +<li><em>td</em> – the C/C++ type’s <a class="reference internal" href="#ref-type-structures"><em>generated type structure</em></a>.</li> +<li><em>flags</em> – any combination of the <a title="SIP_NOT_NONE" class="reference internal" href="#SIP_NOT_NONE"><tt class="xref docutils literal"><span class="pre">SIP_NOT_NONE</span></tt></a> and +<a title="SIP_NO_CONVERTORS" class="reference internal" href="#SIP_NO_CONVERTORS"><tt class="xref docutils literal"><span class="pre">SIP_NO_CONVERTORS</span></tt></a> flags.</li> +</ul> +</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">a non-zero value if the object can be converted.</p> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipClassName"> +PyObject *<tt class="descname">sipClassName</tt><big>(</big>PyObject<em> *obj</em><big>)</big><a class="headerlink" href="#sipClassName" title="Permalink to this definition">¶</a></dt> +<dd><p>This gets the class name of a wrapped instance as a Python string. It +comes with a reference.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>obj</em> – the wrapped instance.</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body">the name of the instance’s class.</td> +</tr> +</tbody> +</table> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p>This is deprecated from SIP v4.8. Instead you should use the +following:</p> +<div class="last highlight-python"><pre>PyString_FromString(obj->ob_type->tp_name)</pre> +</div> +</div> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipConvertFromConstVoidPtr"> +PyObject *<tt class="descname">sipConvertFromConstVoidPtr</tt><big>(</big>const void<em> *cpp</em><big>)</big><a class="headerlink" href="#sipConvertFromConstVoidPtr" title="Permalink to this definition">¶</a></dt> +<dd><p>This creates a <a title="sip.voidptr" class="reference external" href="python_api.html#sip.voidptr"><tt class="xref docutils literal"><span class="pre">sip.voidptr</span></tt></a> object for a memory address. The +object will not be writeable and has no associated size.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>cpp</em> – the memory address.</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body">the <a title="sip.voidptr" class="reference external" href="python_api.html#sip.voidptr"><tt class="xref docutils literal"><span class="pre">sip.voidptr</span></tt></a> object.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipConvertFromConstVoidPtrAndSize"> +PyObject *<tt class="descname">sipConvertFromConstVoidPtrAndSize</tt><big>(</big>const void<em> *cpp</em>, <a title="SIP_SSIZE_T" class="reference internal" href="#SIP_SSIZE_T">SIP_SSIZE_T</a><em> size</em><big>)</big><a class="headerlink" href="#sipConvertFromConstVoidPtrAndSize" title="Permalink to this definition">¶</a></dt> +<dd><p>This creates a <a title="sip.voidptr" class="reference external" href="python_api.html#sip.voidptr"><tt class="xref docutils literal"><span class="pre">sip.voidptr</span></tt></a> object for a memory address. The +object will not be writeable and can be used as an immutable buffer object.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><em>cpp</em> – the memory address.</li> +<li><em>size</em> – the size associated with the address.</li> +</ul> +</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the <a title="sip.voidptr" class="reference external" href="python_api.html#sip.voidptr"><tt class="xref docutils literal"><span class="pre">sip.voidptr</span></tt></a> object.</p> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipConvertFromEnum"> +PyObject *<tt class="descname">sipConvertFromEnum</tt><big>(</big>int<em> eval</em>, const sipTypeDef<em> *td</em><big>)</big><a class="headerlink" href="#sipConvertFromEnum" title="Permalink to this definition">¶</a></dt> +<dd><p>This converts a named C/C++ <tt class="docutils literal"><span class="pre">enum</span></tt> to an instance of the corresponding +generated Python type.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><em>eval</em> – the enumerated value to convert.</li> +<li><em>td</em> – the enum’s <a class="reference internal" href="#ref-type-structures"><em>generated type structure</em></a>.</li> +</ul> +</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the Python object.</p> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipConvertFromInstance"> +PyObject *<tt class="descname">sipConvertFromInstance</tt><big>(</big>void<em> *cpp</em>, <a title="sipWrapperType" class="reference internal" href="#sipWrapperType">sipWrapperType</a><em> *type</em>, PyObject<em> *transferObj</em><big>)</big><a class="headerlink" href="#sipConvertFromInstance" title="Permalink to this definition">¶</a></dt> +<dd><p>This converts a C structure or a C++ class instance to an instance of the +corresponding generated Python type.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><em>cpp</em> – the C/C++ instance.</li> +<li><em>type</em> – the type’s <a class="reference internal" href="#ref-type-objects"><em>generated type object</em></a>.</li> +<li><em>transferObj</em> – this controls the ownership of the returned value.</li> +</ul> +</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the Python object.</p> +</td> +</tr> +</tbody> +</table> +<p>If the C/C++ instance has already been wrapped then the result is a +new reference to the existing class instance object.</p> +<p>If <em>transferObj</em> is <tt class="docutils literal"><span class="pre">NULL</span></tt> and the instance has already been wrapped then +the ownership is unchanged.</p> +<p>If <em>transferObj</em> is <tt class="docutils literal"><span class="pre">NULL</span></tt> and the instance is newly wrapped then +ownership will be with C/C++.</p> +<p>If <em>transferObj</em> is <tt class="docutils literal"><span class="pre">Py_None</span></tt> then ownership is transferred to Python via +a call to <a title="sipTransferBack" class="reference internal" href="#sipTransferBack"><tt class="xref docutils literal"><span class="pre">sipTransferBack()</span></tt></a>.</p> +<p>Otherwise ownership is transferred to C/C++ and the instance associated +with <em>transferObj</em> via a call to <a title="sipTransferTo" class="reference internal" href="#sipTransferTo"><tt class="xref docutils literal"><span class="pre">sipTransferTo()</span></tt></a>.</p> +<p>The Python type is influenced by any applicable +<a class="reference external" href="directives.html#directive-%ConvertToSubClassCode"><tt class="xref docutils literal"><span class="pre">%ConvertToSubClassCode</span></tt></a> code.</p> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">This is deprecated from SIP v4.8. Instead you should use +<a title="sipConvertFromType" class="reference internal" href="#sipConvertFromType"><tt class="xref docutils literal"><span class="pre">sipConvertFromType()</span></tt></a>.</p> +</div> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipConvertFromMappedType"> +PyObject *<tt class="descname">sipConvertFromMappedType</tt><big>(</big>void<em> *cpp</em>, const sipMappedType<em> *mt</em>, PyObject<em> *transferObj</em><big>)</big><a class="headerlink" href="#sipConvertFromMappedType" title="Permalink to this definition">¶</a></dt> +<dd><p>This converts a C structure or a C++ class instance wrapped as a mapped +type to an instance of the corresponding generated Python type.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><em>cpp</em> – the C/C++ instance.</li> +<li><em>mt</em> – the opaque structure returned by <a title="sipFindMappedType" class="reference internal" href="#sipFindMappedType"><tt class="xref docutils literal"><span class="pre">sipFindMappedType()</span></tt></a>.</li> +<li><em>transferObj</em> – this controls the ownership of the returned value.</li> +</ul> +</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the Python object.</p> +</td> +</tr> +</tbody> +</table> +<p>If <em>transferObj</em> is <tt class="docutils literal"><span class="pre">NULL</span></tt> then the ownership is unchanged.</p> +<p>If <em>transferObj</em> is <tt class="docutils literal"><span class="pre">Py_None</span></tt> then ownership is transferred to Python +via a call to <a title="sipTransferBack" class="reference internal" href="#sipTransferBack"><tt class="xref docutils literal"><span class="pre">sipTransferBack()</span></tt></a>.</p> +<p>Otherwise ownership is transferred to C/C++ and the instance associated +with <em>transferObj</em> argument via a call to <a title="sipTransferTo" class="reference internal" href="#sipTransferTo"><tt class="xref docutils literal"><span class="pre">sipTransferTo()</span></tt></a>.</p> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">This is deprecated from SIP v4.8. Instead you should use +<a title="sipConvertFromType" class="reference internal" href="#sipConvertFromType"><tt class="xref docutils literal"><span class="pre">sipConvertFromType()</span></tt></a>.</p> +</div> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipConvertFromNamedEnum"> +PyObject *<tt class="descname">sipConvertFromNamedEnum</tt><big>(</big>int<em> eval</em>, PyTypeObject<em> *type</em><big>)</big><a class="headerlink" href="#sipConvertFromNamedEnum" title="Permalink to this definition">¶</a></dt> +<dd><p>This converts a named C/C++ <tt class="docutils literal"><span class="pre">enum</span></tt> to an instance of the corresponding +generated Python type.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><em>eval</em> – the enumerated value to convert.</li> +<li><em>type</em> – the enum’s <a class="reference internal" href="#ref-type-objects"><em>generated type object</em></a>.</li> +</ul> +</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the Python object.</p> +</td> +</tr> +</tbody> +</table> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">This is deprecated from SIP v4.8. Instead you should use +<a title="sipConvertFromEnum" class="reference internal" href="#sipConvertFromEnum"><tt class="xref docutils literal"><span class="pre">sipConvertFromEnum()</span></tt></a>.</p> +</div> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipConvertFromNewInstance"> +PyObject *<tt class="descname">sipConvertFromNewInstance</tt><big>(</big>void<em> *cpp</em>, <a title="sipWrapperType" class="reference internal" href="#sipWrapperType">sipWrapperType</a><em> *type</em>, PyObject<em> *transferObj</em><big>)</big><a class="headerlink" href="#sipConvertFromNewInstance" title="Permalink to this definition">¶</a></dt> +<dd><p>This converts a new C structure or a C++ class instance to an instance of +the corresponding generated Python type.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><em>cpp</em> – the C/C++ instance.</li> +<li><em>type</em> – the type’s <a class="reference internal" href="#ref-type-objects"><em>generated type object</em></a>.</li> +<li><em>transferObj</em> – this controls the ownership of the returned value.</li> +</ul> +</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the Python object.</p> +</td> +</tr> +</tbody> +</table> +<p>If <em>transferObj</em> is <tt class="docutils literal"><span class="pre">NULL</span></tt> or <tt class="docutils literal"><span class="pre">Py_None</span></tt> then ownership will be with +Python.</p> +<p>Otherwise ownership will be with C/C++ and the instance associated with +<em>transferObj</em>.</p> +<p>The Python type is influenced by any applicable +<a class="reference external" href="directives.html#directive-%ConvertToSubClassCode"><tt class="xref docutils literal"><span class="pre">%ConvertToSubClassCode</span></tt></a> code.</p> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">This is deprecated from SIP v4.8. Instead you should use +<a title="sipConvertFromNewType" class="reference internal" href="#sipConvertFromNewType"><tt class="xref docutils literal"><span class="pre">sipConvertFromNewType()</span></tt></a>.</p> +</div> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipConvertFromNewType"> +PyObject *<tt class="descname">sipConvertFromNewType</tt><big>(</big>void<em> *cpp</em>, const sipTypeDef<em> *td</em>, PyObject<em> *transferObj</em><big>)</big><a class="headerlink" href="#sipConvertFromNewType" title="Permalink to this definition">¶</a></dt> +<dd><p>This converts a new C structure or a C++ class instance to an instance of +the corresponding generated Python type.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><em>cpp</em> – the C/C++ instance.</li> +<li><em>td</em> – the type’s <a class="reference internal" href="#ref-type-structures"><em>generated type structure</em></a>.</li> +<li><em>transferObj</em> – this controls the ownership of the returned value.</li> +</ul> +</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the Python object.</p> +</td> +</tr> +</tbody> +</table> +<p>If <em>transferObj</em> is <tt class="docutils literal"><span class="pre">NULL</span></tt> or <tt class="docutils literal"><span class="pre">Py_None</span></tt> then ownership will be with +Python.</p> +<p>Otherwise ownership will be with C/C++ and the instance associated with +<em>transferObj</em>.</p> +<p>The Python type is influenced by any applicable +<a class="reference external" href="directives.html#directive-%ConvertToSubClassCode"><tt class="xref docutils literal"><span class="pre">%ConvertToSubClassCode</span></tt></a> code.</p> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipConvertFromSequenceIndex"> +<a title="SIP_SSIZE_T" class="reference internal" href="#SIP_SSIZE_T">SIP_SSIZE_T</a> <tt class="descname">sipConvertFromSequenceIndex</tt><big>(</big><a title="SIP_SSIZE_T" class="reference internal" href="#SIP_SSIZE_T">SIP_SSIZE_T</a><em> idx</em>, <a title="SIP_SSIZE_T" class="reference internal" href="#SIP_SSIZE_T">SIP_SSIZE_T</a><em> len</em><big>)</big><a class="headerlink" href="#sipConvertFromSequenceIndex" title="Permalink to this definition">¶</a></dt> +<dd><p>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.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><em>idx</em> – the sequence index.</li> +<li><em>len</em> – the length of the sequence.</li> +</ul> +</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the unsigned array index.</p> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipConvertFromSliceObject"> +int <tt class="descname">sipConvertFromSliceObject</tt><big>(</big>PyObject<em> *slice</em>, <a title="SIP_SSIZE_T" class="reference internal" href="#SIP_SSIZE_T">SIP_SSIZE_T</a><em> length</em>, <a title="SIP_SSIZE_T" class="reference internal" href="#SIP_SSIZE_T">SIP_SSIZE_T</a><em> *start</em>, <a title="SIP_SSIZE_T" class="reference internal" href="#SIP_SSIZE_T">SIP_SSIZE_T</a><em> *stop</em>, <a title="SIP_SSIZE_T" class="reference internal" href="#SIP_SSIZE_T">SIP_SSIZE_T</a><em> *step</em>, <a title="SIP_SSIZE_T" class="reference internal" href="#SIP_SSIZE_T">SIP_SSIZE_T</a><em> *slicelength</em><big>)</big><a class="headerlink" href="#sipConvertFromSliceObject" title="Permalink to this definition">¶</a></dt> +<dd>This is a thin wrapper around the Python <tt class="xref docutils literal"><span class="pre">PySlice_GetIndicesEx()</span></tt> +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.</dd></dl> + +<dl class="cfunction"> +<dt id="sipConvertFromType"> +PyObject *<tt class="descname">sipConvertFromType</tt><big>(</big>void<em> *cpp</em>, const sipTypeDef<em> *td</em>, PyObject<em> *transferObj</em><big>)</big><a class="headerlink" href="#sipConvertFromType" title="Permalink to this definition">¶</a></dt> +<dd><p>This converts a C structure or a C++ class instance to an instance of the +corresponding generated Python type.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><em>cpp</em> – the C/C++ instance.</li> +<li><em>td</em> – the type’s <a class="reference internal" href="#ref-type-structures"><em>generated type structure</em></a>.</li> +<li><em>transferObj</em> – this controls the ownership of the returned value.</li> +</ul> +</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the Python object.</p> +</td> +</tr> +</tbody> +</table> +<p>If the C/C++ instance has already been wrapped then the result is a new +reference to the existing object.</p> +<p>If <em>transferObj</em> is <tt class="docutils literal"><span class="pre">NULL</span></tt> and the instance has already been wrapped then +the ownership is unchanged.</p> +<p>If <em>transferObj</em> is <tt class="docutils literal"><span class="pre">NULL</span></tt> and the instance is newly wrapped then +ownership will be with C/C++.</p> +<p>If <em>transferObj</em> is <tt class="docutils literal"><span class="pre">Py_None</span></tt> then ownership is transferred to Python via +a call to <a title="sipTransferBack" class="reference internal" href="#sipTransferBack"><tt class="xref docutils literal"><span class="pre">sipTransferBack()</span></tt></a>.</p> +<p>Otherwise ownership is transferred to C/C++ and the instance associated +with <em>transferObj</em> via a call to <a title="sipTransferTo" class="reference internal" href="#sipTransferTo"><tt class="xref docutils literal"><span class="pre">sipTransferTo()</span></tt></a>.</p> +<p>The Python class is influenced by any applicable +<a class="reference external" href="directives.html#directive-%ConvertToSubClassCode"><tt class="xref docutils literal"><span class="pre">%ConvertToSubClassCode</span></tt></a> code.</p> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipConvertFromVoidPtr"> +PyObject *<tt class="descname">sipConvertFromVoidPtr</tt><big>(</big>void<em> *cpp</em><big>)</big><a class="headerlink" href="#sipConvertFromVoidPtr" title="Permalink to this definition">¶</a></dt> +<dd><p>This creates a <a title="sip.voidptr" class="reference external" href="python_api.html#sip.voidptr"><tt class="xref docutils literal"><span class="pre">sip.voidptr</span></tt></a> object for a memory address. The +object will be writeable but has no associated size.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>cpp</em> – the memory address.</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body">the <a title="sip.voidptr" class="reference external" href="python_api.html#sip.voidptr"><tt class="xref docutils literal"><span class="pre">sip.voidptr</span></tt></a> object.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipConvertFromVoidPtrAndSize"> +PyObject *<tt class="descname">sipConvertFromVoidPtrAndSize</tt><big>(</big>void<em> *cpp</em>, <a title="SIP_SSIZE_T" class="reference internal" href="#SIP_SSIZE_T">SIP_SSIZE_T</a><em> size</em><big>)</big><a class="headerlink" href="#sipConvertFromVoidPtrAndSize" title="Permalink to this definition">¶</a></dt> +<dd><p>This creates a <a title="sip.voidptr" class="reference external" href="python_api.html#sip.voidptr"><tt class="xref docutils literal"><span class="pre">sip.voidptr</span></tt></a> object for a memory address. The +object will be writeable and can be used as a mutable buffer object.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><em>cpp</em> – the memory address.</li> +<li><em>size</em> – the size associated with the address.</li> +</ul> +</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the <a title="sip.voidptr" class="reference external" href="python_api.html#sip.voidptr"><tt class="xref docutils literal"><span class="pre">sip.voidptr</span></tt></a> object.</p> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipConvertToInstance"> +void *<tt class="descname">sipConvertToInstance</tt><big>(</big>PyObject<em> *obj</em>, <a title="sipWrapperType" class="reference internal" href="#sipWrapperType">sipWrapperType</a><em> *type</em>, PyObject<em> *transferObj</em>, int<em> flags</em>, int<em> *state</em>, int<em> *iserr</em><big>)</big><a class="headerlink" href="#sipConvertToInstance" title="Permalink to this definition">¶</a></dt> +<dd><p>This converts a Python object to an instance of a C structure or C++ class +assuming that a previous call to <a title="sipCanConvertToInstance" class="reference internal" href="#sipCanConvertToInstance"><tt class="xref docutils literal"><span class="pre">sipCanConvertToInstance()</span></tt></a> has +been successful.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><em>obj</em> – the Python object.</li> +<li><em>type</em> – the type’s <a class="reference internal" href="#ref-type-objects"><em>generated type object</em></a>.</li> +<li><em>transferObj</em> – this controls any ownership changes to <em>obj</em>.</li> +<li><em>flags</em> – any combination of the <a title="SIP_NOT_NONE" class="reference internal" href="#SIP_NOT_NONE"><tt class="xref docutils literal"><span class="pre">SIP_NOT_NONE</span></tt></a> and +<a title="SIP_NO_CONVERTORS" class="reference internal" href="#SIP_NO_CONVERTORS"><tt class="xref docutils literal"><span class="pre">SIP_NO_CONVERTORS</span></tt></a> flags.</li> +<li><em>state</em> – the state of the returned C/C++ instance is returned via this pointer.</li> +<li><em>iserr</em> – the error flag is passed and updated via this pointer.</li> +</ul> +</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the C/C++ instance.</p> +</td> +</tr> +</tbody> +</table> +<p>If <em>transferObj</em> is <tt class="docutils literal"><span class="pre">NULL</span></tt> then the ownership is unchanged.</p> +<p>If <em>transferObj</em> is <tt class="docutils literal"><span class="pre">Py_None</span></tt> then ownership is transferred to Python via +a call to <a title="sipTransferBack" class="reference internal" href="#sipTransferBack"><tt class="xref docutils literal"><span class="pre">sipTransferBack()</span></tt></a>.</p> +<p>Otherwise ownership is transferred to C/C++ and <em>obj</em> associated with +<em>transferObj</em> via a call to <a title="sipTransferTo" class="reference internal" href="#sipTransferTo"><tt class="xref docutils literal"><span class="pre">sipTransferTo()</span></tt></a>.</p> +<p>If <em>state</em> is not <tt class="docutils literal"><span class="pre">NULL</span></tt> 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 <a class="reference external" href="directives.html#directive-%ConvertToTypeCode"><tt class="xref docutils literal"><span class="pre">%ConvertToTypeCode</span></tt></a>. The calling code must then release +the value at some point to prevent a memory leak by calling +<a title="sipReleaseInstance" class="reference internal" href="#sipReleaseInstance"><tt class="xref docutils literal"><span class="pre">sipReleaseInstance()</span></tt></a>.</p> +<p>If there is an error then the location <em>iserr</em> 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.)</p> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">This is deprecated from SIP v4.8. Instead you should use +<a title="sipConvertToType" class="reference internal" href="#sipConvertToType"><tt class="xref docutils literal"><span class="pre">sipConvertToType()</span></tt></a>.</p> +</div> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipConvertToMappedType"> +void *<tt class="descname">sipConvertToMappedType</tt><big>(</big>PyObject<em> *obj</em>, const sipMappedType<em> *mt</em>, PyObject<em> *transferObj</em>, int<em> flags</em>, int<em> *state</em>, int<em> *iserr</em><big>)</big><a class="headerlink" href="#sipConvertToMappedType" title="Permalink to this definition">¶</a></dt> +<dd><p>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 +<a title="sipCanConvertToMappedType" class="reference internal" href="#sipCanConvertToMappedType"><tt class="xref docutils literal"><span class="pre">sipCanConvertToMappedType()</span></tt></a> has been successful.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><em>obj</em> – the Python object.</li> +<li><em>mt</em> – the opaque structure returned by <a title="sipFindMappedType" class="reference internal" href="#sipFindMappedType"><tt class="xref docutils literal"><span class="pre">sipFindMappedType()</span></tt></a>.</li> +<li><em>transferObj</em> – this controls any ownership changes to <em>obj</em>.</li> +<li><em>flags</em> – this may be the <a title="SIP_NOT_NONE" class="reference internal" href="#SIP_NOT_NONE"><tt class="xref docutils literal"><span class="pre">SIP_NOT_NONE</span></tt></a> flag.</li> +<li><em>state</em> – the state of the returned C/C++ instance is returned via this pointer.</li> +<li><em>iserr</em> – the error flag is passed and updated via this pointer.</li> +</ul> +</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the C/C++ instance.</p> +</td> +</tr> +</tbody> +</table> +<p>If <em>transferObj</em> is <tt class="docutils literal"><span class="pre">NULL</span></tt> then the ownership is unchanged.</p> +<p>If <em>transferObj</em> is <tt class="docutils literal"><span class="pre">Py_None</span></tt> then ownership is transferred to Python via +a call to <a title="sipTransferBack" class="reference internal" href="#sipTransferBack"><tt class="xref docutils literal"><span class="pre">sipTransferBack()</span></tt></a>.</p> +<p>Otherwise ownership is transferred to C/C++ and <em>obj</em> associated with +<em>transferObj</em> via a call to <a title="sipTransferTo" class="reference internal" href="#sipTransferTo"><tt class="xref docutils literal"><span class="pre">sipTransferTo()</span></tt></a>.</p> +<p>If <em>state</em> is not <tt class="docutils literal"><span class="pre">NULL</span></tt> 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 <a class="reference external" href="directives.html#directive-%ConvertToTypeCode"><tt class="xref docutils literal"><span class="pre">%ConvertToTypeCode</span></tt></a>. The calling code must then release +the value at some point to prevent a memory leak by calling +<a title="sipReleaseMappedType" class="reference internal" href="#sipReleaseMappedType"><tt class="xref docutils literal"><span class="pre">sipReleaseMappedType()</span></tt></a>.</p> +<p>If there is an error then the location <em>iserr</em> 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.)</p> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">This is deprecated from SIP v4.8. Instead you should use +<a title="sipConvertToType" class="reference internal" href="#sipConvertToType"><tt class="xref docutils literal"><span class="pre">sipConvertToType()</span></tt></a></p> +</div> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipConvertToType"> +void *<tt class="descname">sipConvertToType</tt><big>(</big>PyObject<em> *obj</em>, const sipTypeDef<em> *td</em>, PyObject<em> *transferObj</em>, int<em> flags</em>, int<em> *state</em>, int<em> *iserr</em><big>)</big><a class="headerlink" href="#sipConvertToType" title="Permalink to this definition">¶</a></dt> +<dd><p>This converts a Python object to an instance of a C structure, C++ class or +mapped type assuming that a previous call to <a title="sipCanConvertToType" class="reference internal" href="#sipCanConvertToType"><tt class="xref docutils literal"><span class="pre">sipCanConvertToType()</span></tt></a> +has been successful.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><em>obj</em> – the Python object.</li> +<li><em>td</em> – the type’s <a class="reference internal" href="#ref-type-structures"><em>generated type structure</em></a>.</li> +<li><em>transferObj</em> – this controls any ownership changes to <em>obj</em>.</li> +<li><em>flags</em> – any combination of the <a title="SIP_NOT_NONE" class="reference internal" href="#SIP_NOT_NONE"><tt class="xref docutils literal"><span class="pre">SIP_NOT_NONE</span></tt></a> and +<a title="SIP_NO_CONVERTORS" class="reference internal" href="#SIP_NO_CONVERTORS"><tt class="xref docutils literal"><span class="pre">SIP_NO_CONVERTORS</span></tt></a> flags.</li> +<li><em>state</em> – the state of the returned C/C++ instance is returned via this pointer.</li> +<li><em>iserr</em> – the error flag is passed and updated via this pointer.</li> +</ul> +</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the C/C++ instance.</p> +</td> +</tr> +</tbody> +</table> +<p>If <em>transferObj</em> is <tt class="docutils literal"><span class="pre">NULL</span></tt> then the ownership is unchanged. If it is +<tt class="docutils literal"><span class="pre">Py_None</span></tt> then ownership is transferred to Python via a call to +<a title="sipTransferBack" class="reference internal" href="#sipTransferBack"><tt class="xref docutils literal"><span class="pre">sipTransferBack()</span></tt></a>.</p> +<p>Otherwise ownership is transferred to C/C++ and <em>obj</em> associated with +<em>transferObj</em> via a call to <a title="sipTransferTo" class="reference internal" href="#sipTransferTo"><tt class="xref docutils literal"><span class="pre">sipTransferTo()</span></tt></a>.</p> +<p>If <em>state</em> is not <tt class="docutils literal"><span class="pre">NULL</span></tt> 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 <a class="reference external" href="directives.html#directive-%ConvertToTypeCode"><tt class="xref docutils literal"><span class="pre">%ConvertToTypeCode</span></tt></a>. The calling code must then release +the value at some point to prevent a memory leak by calling +<a title="sipReleaseType" class="reference internal" href="#sipReleaseType"><tt class="xref docutils literal"><span class="pre">sipReleaseType()</span></tt></a>.</p> +<p>If there is an error then the location <em>iserr</em> 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.)</p> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipConvertToVoidPtr"> +void *<tt class="descname">sipConvertToVoidPtr</tt><big>(</big>PyObject<em> *obj</em><big>)</big><a class="headerlink" href="#sipConvertToVoidPtr" title="Permalink to this definition">¶</a></dt> +<dd><p>This converts a Python object to a memory address. +<tt class="xref docutils literal"><span class="pre">PyErr_Occurred()</span></tt> must be used to determine if the conversion was +successful.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>obj</em> – the Python object which may be <tt class="docutils literal"><span class="pre">Py_None</span></tt>, a <a title="sip.voidptr" class="reference external" href="python_api.html#sip.voidptr"><tt class="xref docutils literal"><span class="pre">sip.voidptr</span></tt></a> or a +<tt class="xref docutils literal"><span class="pre">PyCObject</span></tt>.</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body">the memory address.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipExportSymbol"> +int <tt class="descname">sipExportSymbol</tt><big>(</big>const char<em> *name</em>, void<em> *sym</em><big>)</big><a class="headerlink" href="#sipExportSymbol" title="Permalink to this definition">¶</a></dt> +<dd><p>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 <a title="sipImportSymbol" class="reference internal" href="#sipImportSymbol"><tt class="xref docutils literal"><span class="pre">sipImportSymbol()</span></tt></a>, by +another module.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><em>name</em> – the name of the symbol.</li> +<li><em>sym</em> – the value of the symbol.</li> +</ul> +</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">0 if there was no error. A negative value is returned if <em>name</em> is +already associated with a symbol or there was some other error.</p> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipFindClass"> +<a title="sipWrapperType" class="reference internal" href="#sipWrapperType">sipWrapperType</a> *<tt class="descname">sipFindClass</tt><big>(</big>const char<em> *type</em><big>)</big><a class="headerlink" href="#sipFindClass" title="Permalink to this definition">¶</a></dt> +<dd><p>This returns a pointer to the <a class="reference internal" href="#ref-type-objects"><em>generated type object +</em></a> corresponding to a C/C++ type.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>type</em> – the C/C++ declaration of the type.</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body">the generated type object. This will not change and may be saved in a +static cache. <tt class="docutils literal"><span class="pre">NULL</span></tt> is returned if the C/C++ type doesn’t exist.</td> +</tr> +</tbody> +</table> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">This is deprecated from SIP v4.8. Instead you should use +<a title="sipFindType" class="reference internal" href="#sipFindType"><tt class="xref docutils literal"><span class="pre">sipFindType()</span></tt></a>.</p> +</div> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipFindMappedType"> +const sipMappedType *<tt class="descname">sipFindMappedType</tt><big>(</big>const char<em> *type</em><big>)</big><a class="headerlink" href="#sipFindMappedType" title="Permalink to this definition">¶</a></dt> +<dd><p>This returns a pointer to an opaque structure describing a mapped type.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>type</em> – the C/C++ declaration of the type.</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body">the opaque structure. This will not change and may be saved in a +static cache. <tt class="docutils literal"><span class="pre">NULL</span></tt> is returned if the C/C++ type doesn’t exist.</td> +</tr> +</tbody> +</table> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">This is deprecated from SIP v4.8. Instead you should use +<a title="sipFindType" class="reference internal" href="#sipFindType"><tt class="xref docutils literal"><span class="pre">sipFindType()</span></tt></a>.</p> +</div> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipFindNamedEnum"> +PyTypeObject *<tt class="descname">sipFindNamedEnum</tt><big>(</big>const char<em> *type</em><big>)</big><a class="headerlink" href="#sipFindNamedEnum" title="Permalink to this definition">¶</a></dt> +<dd><p>This returns a pointer to the <a class="reference internal" href="#ref-enum-type-objects"><em>generated Python type object</em></a> corresponding to a named C/C++ enum.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>type</em> – the C/C++ declaration of the enum.</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body">the generated Python type object. This will not change and may be +saved in a static cache. <tt class="docutils literal"><span class="pre">NULL</span></tt> is returned if the C/C++ enum +doesn’t exist.</td> +</tr> +</tbody> +</table> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">This is deprecated from SIP v4.8. Instead you should use +<a title="sipFindType" class="reference internal" href="#sipFindType"><tt class="xref docutils literal"><span class="pre">sipFindType()</span></tt></a>.</p> +</div> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipFindType"> +const sipTypeDef *<tt class="descname">sipFindType</tt><big>(</big>const char<em> *type</em><big>)</big><a class="headerlink" href="#sipFindType" title="Permalink to this definition">¶</a></dt> +<dd><p>This returns a pointer to the <a class="reference internal" href="#ref-type-structures"><em>generated type structure</em></a> corresponding to a C/C++ type.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>type</em> – the C/C++ declaration of the type.</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body">the generated type structure. This will not change and may be saved in +a static cache. <tt class="docutils literal"><span class="pre">NULL</span></tt> is returned if the C/C++ type doesn’t exist.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipForceConvertToInstance"> +void *<tt class="descname">sipForceConvertToInstance</tt><big>(</big>PyObject<em> *obj</em>, <a title="sipWrapperType" class="reference internal" href="#sipWrapperType">sipWrapperType</a><em> *type</em>, PyObject<em> *transferObj</em>, int<em> flags</em>, int<em> *state</em>, int<em> *iserr</em><big>)</big><a class="headerlink" href="#sipForceConvertToInstance" title="Permalink to this definition">¶</a></dt> +<dd><p>This converts a Python object to an instance of a C structure or C++ class +by calling <a title="sipCanConvertToInstance" class="reference internal" href="#sipCanConvertToInstance"><tt class="xref docutils literal"><span class="pre">sipCanConvertToInstance()</span></tt></a> and, if it is successfull, +calling <a title="sipConvertToInstance" class="reference internal" href="#sipConvertToInstance"><tt class="xref docutils literal"><span class="pre">sipConvertToInstance()</span></tt></a>.</p> +<p>See <a title="sipConvertToInstance" class="reference internal" href="#sipConvertToInstance"><tt class="xref docutils literal"><span class="pre">sipConvertToInstance()</span></tt></a> for a full description of the +arguments.</p> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">This is deprecated from SIP v4.8. Instead you should use +<a title="sipForceConvertToType" class="reference internal" href="#sipForceConvertToType"><tt class="xref docutils literal"><span class="pre">sipForceConvertToType()</span></tt></a>.</p> +</div> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipForceConvertToMappedType"> +void *<tt class="descname">sipForceConvertToMappedType</tt><big>(</big>PyObject<em> *obj</em>, const sipMappedType<em> *mt</em>, PyObject<em> *transferObj</em>, int<em> flags</em>, int<em> *state</em>, int<em> *iserr</em><big>)</big><a class="headerlink" href="#sipForceConvertToMappedType" title="Permalink to this definition">¶</a></dt> +<dd><p>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 +<a title="sipCanConvertToMappedType" class="reference internal" href="#sipCanConvertToMappedType"><tt class="xref docutils literal"><span class="pre">sipCanConvertToMappedType()</span></tt></a> and, if it is successfull, calling +<a title="sipConvertToMappedType" class="reference internal" href="#sipConvertToMappedType"><tt class="xref docutils literal"><span class="pre">sipConvertToMappedType()</span></tt></a>.</p> +<p>See <a title="sipConvertToMappedType" class="reference internal" href="#sipConvertToMappedType"><tt class="xref docutils literal"><span class="pre">sipConvertToMappedType()</span></tt></a> for a full description of the +arguments.</p> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">This is deprecated from SIP v4.8. Instead you should use +<a title="sipForceConvertToType" class="reference internal" href="#sipForceConvertToType"><tt class="xref docutils literal"><span class="pre">sipForceConvertToType()</span></tt></a>.</p> +</div> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipForceConvertToType"> +void *<tt class="descname">sipForceConvertToType</tt><big>(</big>PyObject<em> *obj</em>, const sipTypeDef<em> *td</em>, PyObject<em> *transferObj</em>, int<em> flags</em>, int<em> *state</em>, int<em> *iserr</em><big>)</big><a class="headerlink" href="#sipForceConvertToType" title="Permalink to this definition">¶</a></dt> +<dd><p>This converts a Python object to an instance of a C structure, C++ class or +mapped type by calling <a title="sipCanConvertToType" class="reference internal" href="#sipCanConvertToType"><tt class="xref docutils literal"><span class="pre">sipCanConvertToType()</span></tt></a> and, if it is +successfull, calling <a title="sipConvertToType" class="reference internal" href="#sipConvertToType"><tt class="xref docutils literal"><span class="pre">sipConvertToType()</span></tt></a>.</p> +<p>See <a title="sipConvertToType" class="reference internal" href="#sipConvertToType"><tt class="xref docutils literal"><span class="pre">sipConvertToType()</span></tt></a> for a full description of the arguments.</p> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipFree"> +void <tt class="descname">sipFree</tt><big>(</big>void<em> *mem</em><big>)</big><a class="headerlink" href="#sipFree" title="Permalink to this definition">¶</a></dt> +<dd><p>This returns an area of memory allocated by <a title="sipMalloc" class="reference internal" href="#sipMalloc"><tt class="xref docutils literal"><span class="pre">sipMalloc()</span></tt></a> to the +heap.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>mem</em> – the memory address.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipGetPyObject"> +PyObject *<tt class="descname">sipGetPyObject</tt><big>(</big>void<em> *cppptr</em>, const sipTypeDef<em> *td</em><big>)</big><a class="headerlink" href="#sipGetPyObject" title="Permalink to this definition">¶</a></dt> +<dd><p>This returns a borrowed reference to the Python object for a C structure or +C++ class instance.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><em>cppptr</em> – the pointer to the C/C++ instance.</li> +<li><em>td</em> – the <a class="reference internal" href="#ref-type-structures"><em>generated type structure</em></a> corresponding +to the C/C++ type.</li> +</ul> +</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the Python object or <tt class="docutils literal"><span class="pre">NULL</span></tt> (and no exception is raised) if the +C/C++ instance hasn’t been wrapped.</p> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipGetState"> +int <tt class="descname">sipGetState</tt><big>(</big>PyObject<em> *transferObj</em><big>)</big><a class="headerlink" href="#sipGetState" title="Permalink to this definition">¶</a></dt> +<dd><p>The <a class="reference external" href="directives.html#directive-%ConvertToTypeCode"><tt class="xref docutils literal"><span class="pre">%ConvertToTypeCode</span></tt></a> directive requires that the provided +code returns an <tt class="docutils literal"><span class="pre">int</span></tt> 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.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>transferObj</em> – the object that describes the requested transfer of ownership.</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body">the state of the converted value.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipGetWrapper"> +PyObject *<tt class="descname">sipGetWrapper</tt><big>(</big>void<em> *cppptr</em>, <a title="sipWrapperType" class="reference internal" href="#sipWrapperType">sipWrapperType</a><em> *type</em><big>)</big><a class="headerlink" href="#sipGetWrapper" title="Permalink to this definition">¶</a></dt> +<dd><p>This returns a borrowed reference to the wrapped instance object for a C +structure or C++ class instance.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><em>cppptr</em> – the pointer to the C/C++ instance.</li> +<li><em>type</em> – the <a class="reference internal" href="#ref-type-objects"><em>generated type object</em></a> corresponding to +the C/C++ type.</li> +</ul> +</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the Python object or <tt class="docutils literal"><span class="pre">NULL</span></tt> (and no exception is raised) if the +C/C++ instance hasn’t been wrapped.</p> +</td> +</tr> +</tbody> +</table> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">This is deprecated from SIP v4.8. Instead you should use +<a title="sipGetPyObject" class="reference internal" href="#sipGetPyObject"><tt class="xref docutils literal"><span class="pre">sipGetPyObject()</span></tt></a>.</p> +</div> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipImportSymbol"> +void *<tt class="descname">sipImportSymbol</tt><big>(</big>const char<em> *name</em><big>)</big><a class="headerlink" href="#sipImportSymbol" title="Permalink to this definition">¶</a></dt> +<dd><p>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 <a title="sipExportSymbol" class="reference internal" href="#sipExportSymbol"><tt class="xref docutils literal"><span class="pre">sipExportSymbol()</span></tt></a>, by +another module.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>name</em> – the name of the symbol.</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body">the value of the symbol. <tt class="docutils literal"><span class="pre">NULL</span></tt> is returned if there is no such +symbol.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="ctype"> +<dt id="sipIntTypeClassMap"> +<tt class="descname">sipIntTypeClassMap</tt><a class="headerlink" href="#sipIntTypeClassMap" title="Permalink to this definition">¶</a></dt> +<dd><p>This C structure is used with <a title="sipMapIntToClass" class="reference internal" href="#sipMapIntToClass"><tt class="xref docutils literal"><span class="pre">sipMapIntToClass()</span></tt></a> to define a +mapping between integer based RTTI and <a class="reference internal" href="#ref-type-objects"><em>generated type objects</em></a>. The structure elements are as follows.</p> +<dl class="cmember"> +<dt id="typeInt"> +int <tt class="descname">typeInt</tt><a class="headerlink" href="#typeInt" title="Permalink to this definition">¶</a></dt> +<dd>The integer RTTI.</dd></dl> + +<dl class="cmember"> +<dt> +<tt class="descname">sipWrapperType **pyType.</tt></dt> +<dd>A pointer to the corresponding generated type object.</dd></dl> + +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">This is deprecated from SIP v4.8.</p> +</div> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipIsAPIEnabled"> +int <tt class="descname">sipIsAPIEnabled</tt><big>(</big>const char<em> *name</em>, int<em> from</em>, int<em> to</em><big>)</big><a class="headerlink" href="#sipIsAPIEnabled" title="Permalink to this definition">¶</a></dt> +<dd><p> +<span class="versionmodified">New in version 4.9.</span></p> +<p>This checks to see if the current version number of an API falls within a +given range. See <a class="reference external" href="using.html#ref-incompat-apis"><em>Managing Incompatible APIs</em></a> for more detail.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><em>name</em> – the name of the API.</li> +<li><em>from</em> – the lower bound of the range. For the API to be enabled its version +number must be greater than or equal to <em>from</em>. If <em>from</em> is 0 then +this check isn’t made.</li> +<li><em>to</em> – the upper bound of the range. For the API to be enabled its version +number must be less than <em>to</em>. If <em>to</em> is 0 then this check isn’t +made.</li> +</ul> +</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">a non-zero value if the API is enabled.</p> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipLong_AsUnsignedLong"> +unsigned long <tt class="descname">sipLong_AsUnsignedLong</tt><big>(</big>PyObject<em> *obj</em><big>)</big><a class="headerlink" href="#sipLong_AsUnsignedLong" title="Permalink to this definition">¶</a></dt> +<dd>This function is a thin wrapper around <tt class="xref docutils literal"><span class="pre">PyLong_AsUnsignedLong()</span></tt> +that works around a bug in Python v2.3.x and earlier when converting +integer objects.</dd></dl> + +<dl class="cfunction"> +<dt id="sipMalloc"> +void *<tt class="descname">sipMalloc</tt><big>(</big>size_t<em> nbytes</em><big>)</big><a class="headerlink" href="#sipMalloc" title="Permalink to this definition">¶</a></dt> +<dd><p>This allocates an area of memory on the heap using the Python +<tt class="xref docutils literal"><span class="pre">PyMem_Malloc()</span></tt> function. The memory is freed by calling +<a title="sipFree" class="reference internal" href="#sipFree"><tt class="xref docutils literal"><span class="pre">sipFree()</span></tt></a>.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>nbytes</em> – the number of bytes to allocate.</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body">the memory address. If there was an error then <tt class="docutils literal"><span class="pre">NULL</span></tt> is returned +and a Python exception raised.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipMapIntToClass"> +<a title="sipWrapperType" class="reference internal" href="#sipWrapperType">sipWrapperType</a> *<tt class="descname">sipMapIntToClass</tt><big>(</big>int<em> type</em>, const <a title="sipIntTypeClassMap" class="reference internal" href="#sipIntTypeClassMap">sipIntTypeClassMap</a><em> *map</em>, int<em> maplen</em><big>)</big><a class="headerlink" href="#sipMapIntToClass" title="Permalink to this definition">¶</a></dt> +<dd><p>This can be used in <a class="reference external" href="directives.html#directive-%ConvertToSubClassCode"><tt class="xref docutils literal"><span class="pre">%ConvertToSubClassCode</span></tt></a> code as a +convenient way of converting integer based RTTI to the corresponding +<a class="reference internal" href="#ref-type-objects"><em>generated type object</em></a>.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><em>type</em> – the integer RTTI.</li> +<li><em>map</em> – the table of known RTTI and the corresponding type objects (see +<a title="sipIntTypeClassMap" class="reference internal" href="#sipIntTypeClassMap"><tt class="xref docutils literal"><span class="pre">sipIntTypeClassMap</span></tt></a>). The entries in the table must be sorted +in ascending order of RTTI.</li> +<li><em>maplen</em> – the number of entries in the table.</li> +</ul> +</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the corresponding type object, or <tt class="docutils literal"><span class="pre">NULL</span></tt> if <em>type</em> wasn’t in <em>map</em>.</p> +</td> +</tr> +</tbody> +</table> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">This is deprecated from SIP v4.8.</p> +</div> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipMapStringToClass"> +<a title="sipWrapperType" class="reference internal" href="#sipWrapperType">sipWrapperType</a> *<tt class="descname">sipMapStringToClass</tt><big>(</big>char<em> *type</em>, const <a title="sipStringTypeClassMap" class="reference internal" href="#sipStringTypeClassMap">sipStringTypeClassMap</a><em> *map</em>, int<em> maplen</em><big>)</big><a class="headerlink" href="#sipMapStringToClass" title="Permalink to this definition">¶</a></dt> +<dd><p>This can be used in <a class="reference external" href="directives.html#directive-%ConvertToSubClassCode"><tt class="xref docutils literal"><span class="pre">%ConvertToSubClassCode</span></tt></a> code as a +convenient way of converting <tt class="docutils literal"><span class="pre">'\0'</span></tt> terminated string based RTTI to the +corresponding <a class="reference internal" href="#ref-type-objects"><em>generated type object</em></a>.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><em>type</em> – the string RTTI.</li> +<li><em>map</em> – the table of known RTTI and the corresponding type objects (see +<a title="sipStringTypeClassMap" class="reference internal" href="#sipStringTypeClassMap"><tt class="xref docutils literal"><span class="pre">sipStringTypeClassMap</span></tt></a>). The entries in the table must be +sorted in ascending order of RTTI.</li> +<li><em>maplen</em> – the number of entries in the table.</li> +</ul> +</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the corresponding type object, or <tt class="docutils literal"><span class="pre">NULL</span></tt> if <em>type</em> wasn’t in <em>map</em>.</p> +</td> +</tr> +</tbody> +</table> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">This is deprecated from SIP v4.8.</p> +</div> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipParseResult"> +int <tt class="descname">sipParseResult</tt><big>(</big>int<em> *iserr</em>, PyObject<em> *method</em>, PyObject<em> *result</em>, const char<em> *format</em>, ...<big>)</big><a class="headerlink" href="#sipParseResult" title="Permalink to this definition">¶</a></dt> +<dd><p>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 +<tt class="xref docutils literal"><span class="pre">PyArg_ParseTuple()</span></tt> function.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><em>iserr</em> – if this is not <tt class="docutils literal"><span class="pre">NULL</span></tt> then the location it points to is set to a +non-zero value if there was an error.</li> +<li><em>method</em> – the Python method that returned <em>result</em>.</li> +<li><em>result</em> – the Python object returned by <em>method</em>.</li> +<li><em>format</em> – the format string.</li> +</ul> +</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">0 if there was no error. Otherwise a negative value is returned, and +an exception raised.</p> +</td> +</tr> +</tbody> +</table> +<p>This is normally called by handwritten code specified with the +<a class="reference external" href="directives.html#directive-%VirtualCatcherCode"><tt class="xref docutils literal"><span class="pre">%VirtualCatcherCode</span></tt></a> directive with <em>method</em> being the supplied +<tt class="docutils literal"><span class="pre">sipMethod</span></tt> and <em>result</em> being the value returned by +<a title="sipCallMethod" class="reference internal" href="#sipCallMethod"><tt class="xref docutils literal"><span class="pre">sipCallMethod()</span></tt></a>.</p> +<p>If <em>format</em> begins and ends with parentheses then <em>result</em> must be a Python +tuple and the rest of <em>format</em> is applied to the tuple contents.</p> +<p>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.</p> +<dl class="docutils"> +<dt><tt class="docutils literal"><span class="pre">ae</span></tt> (object) [char *]</dt> +<dd>Convert a Python string-like object of length 1 to a C/C++ <tt class="docutils literal"><span class="pre">char</span></tt> +according to the encoding <tt class="docutils literal"><span class="pre">e</span></tt>. <tt class="docutils literal"><span class="pre">e</span></tt> can either be <tt class="docutils literal"><span class="pre">A</span></tt> for ASCII, +<tt class="docutils literal"><span class="pre">L</span></tt> for Latin-1, or <tt class="docutils literal"><span class="pre">8</span></tt> 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.</dd> +<dt><tt class="docutils literal"><span class="pre">b</span></tt> (integer) [bool *]</dt> +<dd>Convert a Python integer to a C/C++ <tt class="docutils literal"><span class="pre">bool</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">c</span></tt> (string/bytes) [char *]</dt> +<dd>Convert a Python v2 string object or a Python v3 bytes object of length +1 to a C/C++ <tt class="docutils literal"><span class="pre">char</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">d</span></tt> (float) [double *]</dt> +<dd>Convert a Python floating point number to a C/C++ <tt class="docutils literal"><span class="pre">double</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">e</span></tt> (integer) [enum *]</dt> +<dd>Convert a Python integer to an anonymous C/C++ <tt class="docutils literal"><span class="pre">enum</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">f</span></tt> (float) [float *]</dt> +<dd>Convert a Python floating point number to a C/C++ <tt class="docutils literal"><span class="pre">float</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">g</span></tt> (string/bytes) [const char **, <a title="SIP_SSIZE_T" class="reference internal" href="#SIP_SSIZE_T"><tt class="xref docutils literal"><span class="pre">SIP_SSIZE_T</span></tt></a> *]</dt> +<dd>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 +<tt class="docutils literal"><span class="pre">Py_None</span></tt> then the array and length are <tt class="docutils literal"><span class="pre">NULL</span></tt> and zero +respectively.</dd> +<dt><tt class="docutils literal"><span class="pre">h</span></tt> (integer) [short *]</dt> +<dd>Convert a Python integer to a C/C++ <tt class="docutils literal"><span class="pre">short</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">i</span></tt> (integer) [int *]</dt> +<dd>Convert a Python integer to a C/C++ <tt class="docutils literal"><span class="pre">int</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">l</span></tt> (long) [long *]</dt> +<dd>Convert a Python long to a C/C++ <tt class="docutils literal"><span class="pre">long</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">m</span></tt> (long) [unsigned long *]</dt> +<dd>Convert a Python long to a C/C++ <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">long</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">n</span></tt> (long) [long long *]</dt> +<dd>Convert a Python long to a C/C++ <tt class="docutils literal"><span class="pre">long</span> <span class="pre">long</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">o</span></tt> (long) [unsigned long long *]</dt> +<dd>Convert a Python long to a C/C++ <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">long</span> <span class="pre">long</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">s</span></tt> (string/bytes) [const char **]</dt> +<dd><p class="first">Convert a Python v2 string object or a Python v3 bytes object to a +C/C++ <tt class="docutils literal"><span class="pre">'\0'</span></tt> terminated string. If the Python object is <tt class="docutils literal"><span class="pre">Py_None</span></tt> +then the string is <tt class="docutils literal"><span class="pre">NULL</span></tt>.</p> +<div class="last admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">This is deprecated from SIP v4.8. Instead you should use <tt class="docutils literal"><span class="pre">B</span></tt>.</p> +</div> +</dd> +<dt><tt class="docutils literal"><span class="pre">t</span></tt> (long) [unsigned short *]</dt> +<dd>Convert a Python long to a C/C++ <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">short</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">u</span></tt> (long) [unsigned int *]</dt> +<dd>Convert a Python long to a C/C++ <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">int</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">w</span></tt> (unicode/string) [wchar_t *]</dt> +<dd>Convert a Python v2 string or unicode object or a Python v3 string +object of length 1 to a C/C++ wide character.</dd> +<dt><tt class="docutils literal"><span class="pre">x</span></tt> (unicode/string) [wchar_t **]</dt> +<dd>Convert a Python v2 string or unicode object or a Python v3 string +object to a C/C++ <tt class="docutils literal"><span class="pre">L'\0'</span></tt> terminated wide character string. If the +Python object is <tt class="docutils literal"><span class="pre">Py_None</span></tt> then the string is <tt class="docutils literal"><span class="pre">NULL</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">Ae</span></tt> (object) [int, const char **]</dt> +<dd>Convert a Python string-like object to a C/C++ <tt class="docutils literal"><span class="pre">'\0'</span></tt> terminated +string according to the encoding <tt class="docutils literal"><span class="pre">e</span></tt>. <tt class="docutils literal"><span class="pre">e</span></tt> can either be <tt class="docutils literal"><span class="pre">A</span></tt> for +ASCII, <tt class="docutils literal"><span class="pre">L</span></tt> for Latin-1, or <tt class="docutils literal"><span class="pre">8</span></tt> for UTF-8. If the Python object is +<tt class="docutils literal"><span class="pre">Py_None</span></tt> then the string is <tt class="docutils literal"><span class="pre">NULL</span></tt>. The integer uniquely +identifies the object in the context defined by the <tt class="docutils literal"><span class="pre">S</span></tt> 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.</dd> +<dt><tt class="docutils literal"><span class="pre">B</span></tt> (string/bytes) [int, const char **]</dt> +<dd>Convert a Python v2 string object or a Python v3 bytes object to a +C/C++ <tt class="docutils literal"><span class="pre">'\0'</span></tt> terminated string. If the Python object is <tt class="docutils literal"><span class="pre">Py_None</span></tt> +then the string is <tt class="docutils literal"><span class="pre">NULL</span></tt>. The integer uniquely identifies the +object in the context defined by the <tt class="docutils literal"><span class="pre">S</span></tt> format character and allows +an extra reference to the object to be kept to ensure that the string +remains valid.</dd> +<dt><tt class="docutils literal"><span class="pre">Cf</span></tt> (wrapped class) [<a title="sipWrapperType" class="reference internal" href="#sipWrapperType"><tt class="xref docutils literal"><span class="pre">sipWrapperType</span></tt></a> *, int *, void **]</dt> +<dd><p class="first">Convert a Python object to a C structure or a C++ class instance and +return its state as described in <a title="sipConvertToInstance" class="reference internal" href="#sipConvertToInstance"><tt class="xref docutils literal"><span class="pre">sipConvertToInstance()</span></tt></a>. +<tt class="docutils literal"><span class="pre">f</span></tt> is a combination of the following flags encoded as an ASCII +character by adding <tt class="docutils literal"><span class="pre">0</span></tt> to the combined value:</p> +<blockquote> +<p>0x01 disallows the conversion of <tt class="docutils literal"><span class="pre">Py_None</span></tt> to <tt class="docutils literal"><span class="pre">NULL</span></tt></p> +<dl class="docutils"> +<dt>0x02 implements the <a class="reference external" href="annotations.html#fanno-Factory"><tt class="xref docutils literal"><span class="pre">Factory</span></tt></a> and <a class="reference external" href="annotations.html#fanno-TransferBack"><tt class="xref docutils literal"><span class="pre">TransferBack</span></tt></a></dt> +<dd>annotations</dd> +<dt>0x04 suppresses the return of the state of the returned C/C++</dt> +<dd>instance. Note that the <tt class="docutils literal"><span class="pre">int</span> <span class="pre">*</span></tt> used to return the state is +not passed if this flag is specified.</dd> +</dl> +</blockquote> +<div class="last admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">This is deprecated from SIP v4.8. Instead you should use <tt class="docutils literal"><span class="pre">Hf</span></tt>.</p> +</div> +</dd> +<dt><tt class="docutils literal"><span class="pre">Df</span></tt> (wrapped instance) [const <tt class="xref docutils literal"><span class="pre">sipTypeDef</span></tt> *, int *, void **]</dt> +<dd><p class="first">Convert a Python object to a C structure, C++ class or mapped type +instance and return its state as described in +<a title="sipConvertToType" class="reference internal" href="#sipConvertToType"><tt class="xref docutils literal"><span class="pre">sipConvertToType()</span></tt></a>. <tt class="docutils literal"><span class="pre">f</span></tt> is a combination of the following +flags encoded as an ASCII character by adding <tt class="docutils literal"><span class="pre">0</span></tt> to the combined +value:</p> +<blockquote> +<p>0x01 disallows the conversion of <tt class="docutils literal"><span class="pre">Py_None</span></tt> to <tt class="docutils literal"><span class="pre">NULL</span></tt></p> +<dl class="docutils"> +<dt>0x02 implements the <a class="reference external" href="annotations.html#fanno-Factory"><tt class="xref docutils literal"><span class="pre">Factory</span></tt></a> and <a class="reference external" href="annotations.html#fanno-TransferBack"><tt class="xref docutils literal"><span class="pre">TransferBack</span></tt></a></dt> +<dd>annotations</dd> +<dt>0x04 suppresses the return of the state of the returned C/C++</dt> +<dd>instance. Note that the <tt class="docutils literal"><span class="pre">int</span> <span class="pre">*</span></tt> used to return the state is +not passed if this flag is specified.</dd> +</dl> +</blockquote> +<div class="last admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">This is deprecated from SIP v4.10.1. Instead you should use +<tt class="docutils literal"><span class="pre">Hf</span></tt>.</p> +</div> +</dd> +<dt><tt class="docutils literal"><span class="pre">E</span></tt> (wrapped enum) [PyTypeObject *, enum *]</dt> +<dd><p class="first">Convert a Python named enum type to the corresponding C/C++ <tt class="docutils literal"><span class="pre">enum</span></tt>.</p> +<div class="last admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">This is deprecated from SIP v4.8. Instead you should use <tt class="docutils literal"><span class="pre">F</span></tt>.</p> +</div> +</dd> +<dt><tt class="docutils literal"><span class="pre">F</span></tt> (wrapped enum) [<tt class="xref docutils literal"><span class="pre">sipTypeDef</span></tt> *, enum *]</dt> +<dd>Convert a Python named enum type to the corresponding C/C++ <tt class="docutils literal"><span class="pre">enum</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">G</span></tt> (unicode/string) [wchar_t **, <a title="SIP_SSIZE_T" class="reference internal" href="#SIP_SSIZE_T"><tt class="xref docutils literal"><span class="pre">SIP_SSIZE_T</span></tt></a> *]</dt> +<dd>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 <tt class="docutils literal"><span class="pre">Py_None</span></tt> then the array and length are <tt class="docutils literal"><span class="pre">NULL</span></tt> and zero +respectively.</dd> +<dt><tt class="docutils literal"><span class="pre">Hf</span></tt> (wrapped instance) [const <tt class="xref docutils literal"><span class="pre">sipTypeDef</span></tt> *, int *, void **]</dt> +<dd><p class="first">Convert a Python object to a C structure, C++ class or mapped type +instance as described in <a title="sipConvertToType" class="reference internal" href="#sipConvertToType"><tt class="xref docutils literal"><span class="pre">sipConvertToType()</span></tt></a>. <tt class="docutils literal"><span class="pre">f</span></tt> is a +combination of the following flags encoded as an ASCII character by +adding <tt class="docutils literal"><span class="pre">0</span></tt> to the combined value:</p> +<blockquote class="last"> +<p>0x01 disallows the conversion of <tt class="docutils literal"><span class="pre">Py_None</span></tt> to <tt class="docutils literal"><span class="pre">NULL</span></tt></p> +<dl class="docutils"> +<dt>0x02 implements the <a class="reference external" href="annotations.html#fanno-Factory"><tt class="xref docutils literal"><span class="pre">Factory</span></tt></a> and <a class="reference external" href="annotations.html#fanno-TransferBack"><tt class="xref docutils literal"><span class="pre">TransferBack</span></tt></a></dt> +<dd>annotations</dd> +</dl> +<p>0x04 returns a copy of the C/C++ instance.</p> +</blockquote> +</dd> +<dt><tt class="docutils literal"><span class="pre">N</span></tt> (object) [PyTypeObject *, :PyObject **]</dt> +<dd>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 <tt class="docutils literal"><span class="pre">Py_None</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">O</span></tt> (object) [PyObject **]</dt> +<dd>A Python object is returned without any conversions. The reference +count is incremented.</dd> +<dt><tt class="docutils literal"><span class="pre">S</span></tt> [<a title="sipSimpleWrapper" class="reference internal" href="#sipSimpleWrapper"><tt class="xref docutils literal"><span class="pre">sipSimpleWrapper</span></tt></a> *]</dt> +<dd>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.</dd> +<dt><tt class="docutils literal"><span class="pre">T</span></tt> (object) [PyTypeObject *, PyObject **]</dt> +<dd>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 <tt class="docutils literal"><span class="pre">Py_None</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">V</span></tt> (<a title="sip.voidptr" class="reference external" href="python_api.html#sip.voidptr"><tt class="xref docutils literal"><span class="pre">sip.voidptr</span></tt></a>) [void *]</dt> +<dd>Convert a Python <a title="sip.voidptr" class="reference external" href="python_api.html#sip.voidptr"><tt class="xref docutils literal"><span class="pre">sip.voidptr</span></tt></a> object to a C/C++ <tt class="docutils literal"><span class="pre">void</span> <span class="pre">*</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">Z</span></tt> (object) []</dt> +<dd>Check that a Python object is <tt class="docutils literal"><span class="pre">Py_None</span></tt>. No value is returned.</dd> +</dl> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipRegisterAttributeGetter"> +int <tt class="descname">sipRegisterAttributeGetter</tt><big>(</big>const sipTypeDef<em> *td</em>, sipAttrGetterFunc<em> getter</em><big>)</big><a class="headerlink" href="#sipRegisterAttributeGetter" title="Permalink to this definition">¶</a></dt> +<dd><p>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.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><em>td</em> – the optional <a class="reference internal" href="#ref-type-structures"><em>generated type structure</em></a> that +determines which types the handler will be called for.</li> +<li><em>getter</em> – the handler function.</li> +</ul> +</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">0 if there was no error, otherwise -1 is returned.</p> +</td> +</tr> +</tbody> +</table> +<p>If <em>td</em> is not <tt class="docutils literal"><span class="pre">NULL</span></tt> 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.</p> +<p>A handler has the following signature.</p> +<p>int handler(const <tt class="xref docutils literal"><span class="pre">sipTypeDef</span></tt> *td, PyObject *dict)</p> +<blockquote> +<p><em>td</em> is the generated type definition of the type whose dictionary is +to be populated.</p> +<p><em>dict</em> is the dictionary to be populated.</p> +<p>0 if there was no error, otherwise -1 is returned.</p> +</blockquote> +<p>See the section <a class="reference external" href="using.html#ref-lazy-type-attributes"><em>Lazy Type Attributes</em></a> for more details.</p> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipRegisterPyType"> +int <tt class="descname">sipRegisterPyType</tt><big>(</big>PyTypeObject<em> *type</em><big>)</big><a class="headerlink" href="#sipRegisterPyType" title="Permalink to this definition">¶</a></dt> +<dd><p>This registers a Python type object that can be used as the meta-type or +super-type of a wrapped C++ type.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>type</em> – the type object.</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body">0 if there was no error, otherwise -1 is returned.</td> +</tr> +</tbody> +</table> +<p>See the section <a class="reference external" href="using.html#ref-types-metatypes"><em>Types and Meta-types</em></a> for more details.</p> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipReleaseInstance"> +void <tt class="descname">sipReleaseInstance</tt><big>(</big>void<em> *cpp</em>, <a title="sipWrapperType" class="reference internal" href="#sipWrapperType">sipWrapperType</a><em> *type</em>, int<em> state</em><big>)</big><a class="headerlink" href="#sipReleaseInstance" title="Permalink to this definition">¶</a></dt> +<dd><p>This destroys a wrapped C/C++ instance if it was a temporary instance. It +is called after a call to either <a title="sipConvertToInstance" class="reference internal" href="#sipConvertToInstance"><tt class="xref docutils literal"><span class="pre">sipConvertToInstance()</span></tt></a> or +<a title="sipForceConvertToInstance" class="reference internal" href="#sipForceConvertToInstance"><tt class="xref docutils literal"><span class="pre">sipForceConvertToInstance()</span></tt></a>.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><em>cpp</em> – the C/C++ instance.</li> +<li><em>type</em> – the type’s <a class="reference internal" href="#ref-type-objects"><em>generated type object</em></a>.</li> +<li><em>state</em> – describes the state of the C/C++ instance.</li> +</ul> +</td> +</tr> +</tbody> +</table> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">This is deprecated from SIP v4.8. Instead you should use +<a title="sipReleaseType" class="reference internal" href="#sipReleaseType"><tt class="xref docutils literal"><span class="pre">sipReleaseType()</span></tt></a>.</p> +</div> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipReleaseMappedType"> +void <tt class="descname">sipReleaseMappedType</tt><big>(</big>void<em> *cpp</em>, const sipMappedType<em> *mt</em>, int<em> state</em><big>)</big><a class="headerlink" href="#sipReleaseMappedType" title="Permalink to this definition">¶</a></dt> +<dd><p>This destroys a wrapped C/C++ mapped type if it was a temporary instance. +It is called after a call to either <a title="sipConvertToMappedType" class="reference internal" href="#sipConvertToMappedType"><tt class="xref docutils literal"><span class="pre">sipConvertToMappedType()</span></tt></a> or +<a title="sipForceConvertToMappedType" class="reference internal" href="#sipForceConvertToMappedType"><tt class="xref docutils literal"><span class="pre">sipForceConvertToMappedType()</span></tt></a>.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><em>cpp</em> – the C/C++ instance.</li> +<li><em>mt</em> – the opaque structure returned by <a title="sipFindMappedType" class="reference internal" href="#sipFindMappedType"><tt class="xref docutils literal"><span class="pre">sipFindMappedType()</span></tt></a>.</li> +<li><em>state</em> – describes the state of the C/C++ instance.</li> +</ul> +</td> +</tr> +</tbody> +</table> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">This is deprecated from SIP v4.8. Instead you should use +<a title="sipReleaseType" class="reference internal" href="#sipReleaseType"><tt class="xref docutils literal"><span class="pre">sipReleaseType()</span></tt></a>.</p> +</div> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipReleaseType"> +void <tt class="descname">sipReleaseType</tt><big>(</big>void<em> *cpp</em>, const sipTypeDef<em> *td</em>, int<em> state</em><big>)</big><a class="headerlink" href="#sipReleaseType" title="Permalink to this definition">¶</a></dt> +<dd><p>This destroys a wrapped C/C++ or mapped type instance if it was a temporary +instance. It is called after a call to either <a title="sipConvertToType" class="reference internal" href="#sipConvertToType"><tt class="xref docutils literal"><span class="pre">sipConvertToType()</span></tt></a> +or <a title="sipForceConvertToType" class="reference internal" href="#sipForceConvertToType"><tt class="xref docutils literal"><span class="pre">sipForceConvertToType()</span></tt></a>.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><em>cpp</em> – the C/C++ instance.</li> +<li><em>td</em> – the type’s <a class="reference internal" href="#ref-type-structures"><em>generated type structure</em></a>.</li> +<li><em>state</em> – describes the state of the C/C++ instance.</li> +</ul> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipResolveTypedef"> +const char *<tt class="descname">sipResolveTypedef</tt><big>(</big>const char<em> *name</em><big>)</big><a class="headerlink" href="#sipResolveTypedef" title="Permalink to this definition">¶</a></dt> +<dd><p>This returns the value of a C/C++ typedef.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>name</em> – the name of the typedef.</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body">the value of the typedef or <tt class="docutils literal"><span class="pre">NULL</span></tt> if there was no such typedef.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="ctype"> +<dt id="sipSimpleWrapper"> +<tt class="descname">sipSimpleWrapper</tt><a class="headerlink" href="#sipSimpleWrapper" title="Permalink to this definition">¶</a></dt> +<dd><p>This is a C structure that represents a Python wrapped instance whose type +is <tt class="xref docutils literal"><span class="pre">sip.simplewrapper</span></tt>. It is an extension of the <tt class="docutils literal"><span class="pre">PyObject</span></tt> +structure and so may be safely cast to it.</p> +<dl class="cmember"> +<dt id="user"> +PyObject *<tt class="descname">user</tt><a class="headerlink" href="#user" title="Permalink to this definition">¶</a></dt> +<dd>This can be used for any purpose by handwritten code and will +automatically be garbage collected at the appropriate time.</dd></dl> + +</dd></dl> + +<dl class="cvar"> +<dt id="sipSimpleWrapper_Type"> +PyTypeObject *<tt class="descname">sipSimpleWrapper_Type</tt><a class="headerlink" href="#sipSimpleWrapper_Type" title="Permalink to this definition">¶</a></dt> +<dd>This is the type of a <a title="sipSimpleWrapper" class="reference internal" href="#sipSimpleWrapper"><tt class="xref docutils literal"><span class="pre">sipSimpleWrapper</span></tt></a> structure and is the C +implementation of <tt class="xref docutils literal"><span class="pre">sip.simplewrapper</span></tt>. It may be safely cast to +<a title="sipWrapperType" class="reference internal" href="#sipWrapperType"><tt class="xref docutils literal"><span class="pre">sipWrapperType</span></tt></a>.</dd></dl> + +<dl class="ctype"> +<dt id="sipStringTypeClassMap"> +<tt class="descname">sipStringTypeClassMap</tt><a class="headerlink" href="#sipStringTypeClassMap" title="Permalink to this definition">¶</a></dt> +<dd><p>This C structure is used with <a title="sipMapStringToClass" class="reference internal" href="#sipMapStringToClass"><tt class="xref docutils literal"><span class="pre">sipMapStringToClass()</span></tt></a> to define a +mapping between <tt class="docutils literal"><span class="pre">'\0'</span></tt> terminated string based RTTI and +<a class="reference internal" href="#ref-type-objects"><em>Generated Type Objects</em></a>. The structure elements are as follows.</p> +<dl class="cmember"> +<dt id="typeString"> +char *<tt class="descname">typeString</tt><a class="headerlink" href="#typeString" title="Permalink to this definition">¶</a></dt> +<dd>The <tt class="docutils literal"><span class="pre">'\0'</span></tt> terminated string RTTI.</dd></dl> + +<dl class="cmember"> +<dt> +<tt class="descname">sipWrapperType **pyType.</tt></dt> +<dd>A pointer to the corresponding generated type object.</dd></dl> + +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">This is deprecated from SIP v4.8.</p> +</div> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipTransferBack"> +void <tt class="descname">sipTransferBack</tt><big>(</big>PyObject<em> *obj</em><big>)</big><a class="headerlink" href="#sipTransferBack" title="Permalink to this definition">¶</a></dt> +<dd><p>This transfers ownership of a Python wrapped instance to Python (see +<a class="reference external" href="using.html#ref-object-ownership"><em>Ownership of Objects</em></a>).</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>obj</em> – the wrapped instance.</td> +</tr> +</tbody> +</table> +<p>In addition, any association of the instance with regard to the cyclic +garbage collector with another instance is removed.</p> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipTransferBreak"> +void <tt class="descname">sipTransferBreak</tt><big>(</big>PyObject<em> *obj</em><big>)</big><a class="headerlink" href="#sipTransferBreak" title="Permalink to this definition">¶</a></dt> +<dd><p>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++.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>obj</em> – the wrapped instance.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipTransferTo"> +void <tt class="descname">sipTransferTo</tt><big>(</big>PyObject<em> *obj</em>, PyObject<em> *owner</em><big>)</big><a class="headerlink" href="#sipTransferTo" title="Permalink to this definition">¶</a></dt> +<dd><p>This transfers ownership of a Python wrapped instance to C++ (see +<a class="reference external" href="using.html#ref-object-ownership"><em>Ownership of Objects</em></a>).</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><em>obj</em> – the wrapped instance.</li> +<li><em>owner</em> – an optional wrapped instance that <em>obj</em> becomes associated with with +regard to the cyclic garbage collector. If <em>owner</em> is <tt class="docutils literal"><span class="pre">NULL</span></tt> then no +such association is made. If <em>owner</em> is the same value as <em>obj</em> then +any reference cycles involving <em>obj</em> can never be detected or broken by +the cyclic garbage collector. Responsibility for calling the C++ +instance’s destructor is always transfered to C++.</li> +</ul> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipTypeAsPyTypeObject"> +PyTypeObject *<tt class="descname">sipTypeAsPyTypeObject</tt><big>(</big>sipTypeDef<em> *td</em><big>)</big><a class="headerlink" href="#sipTypeAsPyTypeObject" title="Permalink to this definition">¶</a></dt> +<dd><p>This returns a pointer to the Python type object that SIP creates for a +<a class="reference internal" href="#ref-type-structures"><em>generated type structure</em></a>.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>td</em> – the type structure.</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body">the Python type object. If the type structure refers to a mapped type +then <tt class="docutils literal"><span class="pre">NULL</span></tt> will be returned.</td> +</tr> +</tbody> +</table> +<p>If the type structure refers to a C structure or C++ class then the +Python type object may be safely cast to a <a title="sipWrapperType" class="reference internal" href="#sipWrapperType"><tt class="xref docutils literal"><span class="pre">sipWrapperType</span></tt></a>.</p> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipTypeFromPyTypeObject"> +const sipTypeDef *<tt class="descname">sipTypeFromPyTypeObject</tt><big>(</big>PyTypeObject<em> *py_type</em><big>)</big><a class="headerlink" href="#sipTypeFromPyTypeObject" title="Permalink to this definition">¶</a></dt> +<dd><p>This returns the <a class="reference internal" href="#ref-type-structures"><em>generated type structure</em></a> for +a Python type object.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>py_type</em> – the Python type object.</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body">the type structure or <tt class="docutils literal"><span class="pre">NULL</span></tt> if the Python type object doesn’t +correspond to a type structure.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipTypeIsClass"> +int <tt class="descname">sipTypeIsClass</tt><big>(</big>sipTypeDef<em> *td</em><big>)</big><a class="headerlink" href="#sipTypeIsClass" title="Permalink to this definition">¶</a></dt> +<dd><p>This checks if a <a class="reference internal" href="#ref-type-structures"><em>generated type structure</em></a> +refers to a C structure or C++ class.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>td</em> – the type structure.</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body">a non-zero value if the type structure refers to a structure or class.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipTypeIsEnum"> +int <tt class="descname">sipTypeIsEnum</tt><big>(</big>sipTypeDef<em> *td</em><big>)</big><a class="headerlink" href="#sipTypeIsEnum" title="Permalink to this definition">¶</a></dt> +<dd><p>This checks if a <a class="reference internal" href="#ref-type-structures"><em>generated type structure</em></a> +refers to a named enum.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>td</em> – the type structure.</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body">a non-zero value if the type structure refers to an enum.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipTypeIsMapped"> +int <tt class="descname">sipTypeIsMapped</tt><big>(</big>sipTypeDef<em> *td</em><big>)</big><a class="headerlink" href="#sipTypeIsMapped" title="Permalink to this definition">¶</a></dt> +<dd><p>This checks if a <a class="reference internal" href="#ref-type-structures"><em>generated type structure</em></a> +refers to a mapped type.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>td</em> – the type structure.</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body">a non-zero value if the type structure refers to a mapped type.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipTypeIsNamespace"> +int <tt class="descname">sipTypeIsNamespace</tt><big>(</big>sipTypeDef<em> *td</em><big>)</big><a class="headerlink" href="#sipTypeIsNamespace" title="Permalink to this definition">¶</a></dt> +<dd><p>This checks if a <a class="reference internal" href="#ref-type-structures"><em>generated type structure</em></a> +refers to a C++ namespace.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>td</em> – the type structure.</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body">a non-zero value if the type structure refers to a namespace.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipTypeName"> +const char *<tt class="descname">sipTypeName</tt><big>(</big>const sipTypeDef<em> *td</em><big>)</big><a class="headerlink" href="#sipTypeName" title="Permalink to this definition">¶</a></dt> +<dd><p>This returns the C/C++ name of a wrapped type.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>td</em> – the type’s <a class="reference internal" href="#ref-type-structures"><em>generated type structure</em></a>.</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body">the name of the C/C++ type.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipTypeScope"> +const sipTypeDef *<tt class="descname">sipTypeScope</tt><big>(</big>const sipTypeDef<em> *td</em><big>)</big><a class="headerlink" href="#sipTypeScope" title="Permalink to this definition">¶</a></dt> +<dd><p>This returns the <a class="reference internal" href="#ref-type-structures"><em>generated type structure</em></a> of +the enclosing scope of another generated type structure.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>td</em> – the type structure.</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body">the type structure of the scope or <tt class="docutils literal"><span class="pre">NULL</span></tt> if the type has no scope.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="cvar"> +<dt id="sipVoidPtr_Type"> +PyTypeObject *<tt class="descname">sipVoidPtr_Type</tt><a class="headerlink" href="#sipVoidPtr_Type" title="Permalink to this definition">¶</a></dt> +<dd>This is the type of a <tt class="docutils literal"><span class="pre">PyObject</span></tt> structure that is used to wrap a +<tt class="docutils literal"><span class="pre">void</span> <span class="pre">*</span></tt>.</dd></dl> + +<dl class="ctype"> +<dt id="sipWrapper"> +<tt class="descname">sipWrapper</tt><a class="headerlink" href="#sipWrapper" title="Permalink to this definition">¶</a></dt> +<dd>This is a C structure that represents a Python wrapped instance whose type +is <a title="sip.wrapper" class="reference external" href="python_api.html#sip.wrapper"><tt class="xref docutils literal"><span class="pre">sip.wrapper</span></tt></a>. It is an extension of the +<a title="sipSimpleWrapper" class="reference internal" href="#sipSimpleWrapper"><tt class="xref docutils literal"><span class="pre">sipSimpleWrapper</span></tt></a> and <tt class="docutils literal"><span class="pre">PyObject</span></tt> structures and so may be safely +cast to both.</dd></dl> + +<dl class="cfunction"> +<dt id="sipWrapper_Check"> +int <tt class="descname">sipWrapper_Check</tt><big>(</big>PyObject<em> *obj</em><big>)</big><a class="headerlink" href="#sipWrapper_Check" title="Permalink to this definition">¶</a></dt> +<dd><p>This checks if a Python object is a wrapped instance.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>obj</em> – the Python object.</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body">a non-zero value if the Python object is a wrapped instance.</td> +</tr> +</tbody> +</table> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p>This is deprecated from SIP v4.8. Instead you should use the +following:</p> +<div class="last highlight-python"><div class="highlight"><pre><span class="n">PyObject_TypeCheck</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="n">sipWrapper_Type</span><span class="p">)</span> +</pre></div> +</div> +</div> +</dd></dl> + +<dl class="cvar"> +<dt id="sipWrapper_Type"> +PyTypeObject *<tt class="descname">sipWrapper_Type</tt><a class="headerlink" href="#sipWrapper_Type" title="Permalink to this definition">¶</a></dt> +<dd>This is the type of a <a title="sipWrapper" class="reference internal" href="#sipWrapper"><tt class="xref docutils literal"><span class="pre">sipWrapper</span></tt></a> structure and is the C +implementation of <a title="sip.wrapper" class="reference external" href="python_api.html#sip.wrapper"><tt class="xref docutils literal"><span class="pre">sip.wrapper</span></tt></a>. It may be safely cast to +<a title="sipWrapperType" class="reference internal" href="#sipWrapperType"><tt class="xref docutils literal"><span class="pre">sipWrapperType</span></tt></a>.</dd></dl> + +<dl class="ctype"> +<dt id="sipWrapperType"> +<tt class="descname">sipWrapperType</tt><a class="headerlink" href="#sipWrapperType" title="Permalink to this definition">¶</a></dt> +<dd>This is a C structure that represents a SIP generated type object. It is +an extension of the <tt class="docutils literal"><span class="pre">PyTypeObject</span></tt> structure (which is itself an +extension of the <tt class="docutils literal"><span class="pre">PyObject</span></tt> structure) and so may be safely cast to +<tt class="docutils literal"><span class="pre">PyTypeObject</span></tt> (and <tt class="docutils literal"><span class="pre">PyObject</span></tt>).</dd></dl> + +<dl class="cvar"> +<dt id="sipWrapperType_Type"> +PyTypeObject *<tt class="descname">sipWrapperType_Type</tt><a class="headerlink" href="#sipWrapperType_Type" title="Permalink to this definition">¶</a></dt> +<dd>This is the type of a <a title="sipWrapperType" class="reference internal" href="#sipWrapperType"><tt class="xref docutils literal"><span class="pre">sipWrapperType</span></tt></a> structure and is the C +implementation of <a title="sip.wrappertype" class="reference external" href="python_api.html#sip.wrappertype"><tt class="xref docutils literal"><span class="pre">sip.wrappertype</span></tt></a>.</dd></dl> + +<div class="section" id="generated-type-structures"> +<span id="ref-type-structures"></span><h2>Generated Type Structures<a class="headerlink" href="#generated-type-structures" title="Permalink to this headline">¶</a></h2> +<p>SIP generates an opaque type structure for each C structure, C++ class, C++ +namespace, named enum or mapped type being wrapped. These are +<tt class="xref docutils literal"><span class="pre">sipTypeDef</span></tt> structures and are used extensively by the SIP API.</p> +<p>The names of these structure are prefixed by <tt class="docutils literal"><span class="pre">sipType_</span></tt>.</p> +<p>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 <tt class="docutils literal"><span class="pre">::</span></tt> +scope separators are replaced by an underscore. For example, the type object +for class <tt class="docutils literal"><span class="pre">Klass</span></tt> is <tt class="docutils literal"><span class="pre">sipType_Klass</span></tt>.</p> +<p>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 <a title="sipFindType" class="reference internal" href="#sipFindType"><tt class="xref docutils literal"><span class="pre">sipFindType()</span></tt></a>.</p> +<p>The type structures of all imported types are available to handwritten code.</p> +</div> +<div class="section" id="generated-type-objects"> +<span id="ref-type-objects"></span><h2>Generated Type Objects<a class="headerlink" href="#generated-type-objects" title="Permalink to this headline">¶</a></h2> +<p>SIP generates a <a title="sipWrapperType" class="reference internal" href="#sipWrapperType"><tt class="xref docutils literal"><span class="pre">sipWrapperType</span></tt></a> type object for each C structure or +C++ class being wrapped.</p> +<p>These objects are named with the structure or class name prefixed by +<tt class="docutils literal"><span class="pre">sipClass_</span></tt>. For example, the type object for class <tt class="docutils literal"><span class="pre">Klass</span></tt> is +<tt class="docutils literal"><span class="pre">sipClass_Klass</span></tt>.</p> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">Using these names is deprecated from SIP v4.8. Instead use the +corresponding generated type structure (see <a class="reference internal" href="#ref-type-structures"><em>Generated Type Structures</em></a>) and +<a title="sipTypeAsPyTypeObject" class="reference internal" href="#sipTypeAsPyTypeObject"><tt class="xref docutils literal"><span class="pre">sipTypeAsPyTypeObject()</span></tt></a>.</p> +</div> +</div> +<div class="section" id="generated-named-enum-type-objects"> +<span id="ref-enum-type-objects"></span><h2>Generated Named Enum Type Objects<a class="headerlink" href="#generated-named-enum-type-objects" title="Permalink to this headline">¶</a></h2> +<p>SIP generates a type object for each named enum being wrapped. These are +PyTypeObject structures. (Anonymous enums are wrapped as Python integers.)</p> +<p>These objects are named with the fully qualified enum name (i.e. including any +enclosing scope) prefixed by <tt class="docutils literal"><span class="pre">sipEnum_</span></tt>. For example, the type object for +enum <tt class="docutils literal"><span class="pre">Enum</span></tt> defined in class <tt class="docutils literal"><span class="pre">Klass</span></tt> is <tt class="docutils literal"><span class="pre">sipEnum_Klass_Enum</span></tt>.</p> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">Using these names is deprecated from SIP v4.8. Instead use the +corresponding generated type structure (see <a class="reference internal" href="#ref-type-structures"><em>Generated Type Structures</em></a>) and +<a title="sipTypeAsPyTypeObject" class="reference internal" href="#sipTypeAsPyTypeObject"><tt class="xref docutils literal"><span class="pre">sipTypeAsPyTypeObject()</span></tt></a>.</p> +</div> +</div> +<div class="section" id="generated-derived-classes"> +<span id="ref-derived-classes"></span><h2>Generated Derived Classes<a class="headerlink" href="#generated-derived-classes" title="Permalink to this headline">¶</a></h2> +<p>For most C++ classes being wrapped SIP generates a derived class with the same +name prefixed by <tt class="docutils literal"><span class="pre">sip</span></tt>. For example, the derived class for class <tt class="docutils literal"><span class="pre">Klass</span></tt> +is <tt class="docutils literal"><span class="pre">sipKlass</span></tt>.</p> +<p>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.</p> +<p>Most of the time handwritten code should ignore the derived classes. The only +exception is that handwritten constructor code specified using the +<a class="reference external" href="directives.html#directive-%MethodCode"><tt class="xref docutils literal"><span class="pre">%MethodCode</span></tt></a> directive should call the derived class’s constructor +(which has the same C++ signature) rather then the wrapped class’s constructor.</p> +</div> +<div class="section" id="generated-exception-objects"> +<span id="ref-exception-objects"></span><h2>Generated Exception Objects<a class="headerlink" href="#generated-exception-objects" title="Permalink to this headline">¶</a></h2> +<p>SIP generates a Python object for each exception defined with the +<a class="reference external" href="directives.html#directive-%Exception"><tt class="xref docutils literal"><span class="pre">%Exception</span></tt></a> directive.</p> +<p>These objects are named with the fully qualified exception name (i.e. including +any enclosing scope) prefixed by <tt class="docutils literal"><span class="pre">sipException_</span></tt>. For example, the type +object for enum <tt class="docutils literal"><span class="pre">Except</span></tt> defined in class <tt class="docutils literal"><span class="pre">Klass</span></tt> is +<tt class="docutils literal"><span class="pre">sipException_Klass_Except</span></tt>.</p> +<p>The objects of all imported exceptions are available to handwritten code.</p> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference external" href="#">C API for Handwritten Code</a><ul> +<li><a class="reference external" href="#generated-type-structures">Generated Type Structures</a></li> +<li><a class="reference external" href="#generated-type-objects">Generated Type Objects</a></li> +<li><a class="reference external" href="#generated-named-enum-type-objects">Generated Named Enum Type Objects</a></li> +<li><a class="reference external" href="#generated-derived-classes">Generated Derived Classes</a></li> +<li><a class="reference external" href="#generated-exception-objects">Generated Exception Objects</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="annotations.html" + title="previous chapter">Annotations</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="embedding.html" + title="next chapter">Using the C API when Embedding</a></p> + <div id="searchbox" style="display: none"> + <h3>Quick search</h3> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" size="18" /> + <input type="submit" value="Go" /> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </form> + <p class="searchtip" style="font-size: 90%"> + Enter search terms or a module, class or function name. + </p> + </div> + <script type="text/javascript">$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="modindex.html" title="Global Module Index" + >modules</a> |</li> + <li class="right" > + <a href="embedding.html" title="Using the C API when Embedding" + >next</a> |</li> + <li class="right" > + <a href="annotations.html" title="Annotations" + >previous</a> |</li> + <li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2010 Riverbank Computing Limited. + Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.4. + </div> + </body> +</html>
\ No newline at end of file diff --git a/doc/html/command_line.html b/doc/html/command_line.html new file mode 100644 index 0000000..f20045a --- /dev/null +++ b/doc/html/command_line.html @@ -0,0 +1,259 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + + <title>The SIP Command Line — SIP 4.10.5 Reference Guide</title> + <link rel="stylesheet" href="_static/default.css" type="text/css" /> + <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '#', + VERSION: '4.10.5', + COLLAPSE_MODINDEX: false, + FILE_SUFFIX: '.html', + HAS_SOURCE: true + }; + </script> + <script type="text/javascript" src="_static/jquery.js"></script> + <script type="text/javascript" src="_static/doctools.js"></script> + <link rel="top" title="SIP 4.10.5 Reference Guide" href="index.html" /> + <link rel="next" title="SIP Specification Files" href="specification_files.html" /> + <link rel="prev" title="Using SIP" href="using.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="modindex.html" title="Global Module Index" + accesskey="M">modules</a> |</li> + <li class="right" > + <a href="specification_files.html" title="SIP Specification Files" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="using.html" title="Using SIP" + accesskey="P">previous</a> |</li> + <li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="the-sip-command-line"> +<span id="ref-command-line"></span><h1>The SIP Command Line<a class="headerlink" href="#the-sip-command-line" title="Permalink to this headline">¶</a></h1> +<p>The syntax of the SIP command line is:</p> +<div class="highlight-python"><div class="highlight"><pre><span class="n">sip</span> <span class="p">[</span><span class="n">options</span><span class="p">]</span> <span class="p">[</span><span class="n">specification</span><span class="p">]</span> +</pre></div> +</div> +<p><tt class="docutils literal"><span class="pre">specification</span></tt> is the name of the specification file for the module. If it +is omitted then <tt class="docutils literal"><span class="pre">stdin</span></tt> is used.</p> +<p>The full set of command line options is:</p> +<dl class="cmdoption"> +<dt id="cmdoption-sip-h"> +<tt class="descname">-h</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-sip-h" title="Permalink to this definition">¶</a></dt> +<dd>Display a help message.</dd></dl> + +<dl class="cmdoption"> +<dt id="cmdoption-sip-V"> +<tt class="descname">-V</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-sip-V" title="Permalink to this definition">¶</a></dt> +<dd>Display the SIP version number.</dd></dl> + +<dl class="cmdoption"> +<dt id="cmdoption-sip-a"> +<tt class="descname">-a</tt><tt class="descclassname"> <FILE></tt><a class="headerlink" href="#cmdoption-sip-a" title="Permalink to this definition">¶</a></dt> +<dd>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.</dd></dl> + +<dl class="cmdoption"> +<dt id="cmdoption-sip-b"> +<tt class="descname">-b</tt><tt class="descclassname"> <FILE></tt><a class="headerlink" href="#cmdoption-sip-b" title="Permalink to this definition">¶</a></dt> +<dd>The name of the build file to generate. This file contains the information +about the module needed by the <a class="reference external" href="build_system.html#ref-build-system"><em>SIP build system</em></a> +to generate a platform and compiler specific Makefile for the module. By +default the file is not generated.</dd></dl> + +<dl class="cmdoption"> +<dt id="cmdoption-sip-c"> +<tt class="descname">-c</tt><tt class="descclassname"> <DIR></tt><a class="headerlink" href="#cmdoption-sip-c" title="Permalink to this definition">¶</a></dt> +<dd>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.</dd></dl> + +<dl class="cmdoption"> +<dt id="cmdoption-sip-d"> +<tt class="descname">-d</tt><tt class="descclassname"> <FILE></tt><a class="headerlink" href="#cmdoption-sip-d" title="Permalink to this definition">¶</a></dt> +<dd>The name of the documentation file to generate. Documentation is included +in specification files using the <a class="reference external" href="directives.html#directive-%Doc"><tt class="xref docutils literal"><span class="pre">%Doc</span></tt></a> and +<a class="reference external" href="directives.html#directive-%ExportedDoc"><tt class="xref docutils literal"><span class="pre">%ExportedDoc</span></tt></a> directives. By default the file is not +generated.</dd></dl> + +<dl class="cmdoption"> +<dt id="cmdoption-sip-e"> +<tt class="descname">-e</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-sip-e" title="Permalink to this definition">¶</a></dt> +<dd>Support for C++ exceptions is enabled. This causes all calls to C++ code +to be enclosed in <tt class="docutils literal"><span class="pre">try</span></tt>/<tt class="docutils literal"><span class="pre">catch</span></tt> blocks and C++ exceptions to be +converted to Python exceptions. By default exception support is disabled.</dd></dl> + +<dl class="cmdoption"> +<dt id="cmdoption-sip-g"> +<tt class="descname">-g</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-sip-g" title="Permalink to this definition">¶</a></dt> +<dd>The Python GIL is released before making any calls to the C/C++ library +being wrapped and reacquired afterwards. See <a class="reference external" href="using.html#ref-gil"><em>The Python Global Interpreter Lock</em></a> and the +<a class="reference external" href="annotations.html#fanno-ReleaseGIL"><tt class="xref docutils literal"><span class="pre">ReleaseGIL</span></tt></a> and <a class="reference external" href="annotations.html#fanno-HoldGIL"><tt class="xref docutils literal"><span class="pre">HoldGIL</span></tt></a> annotations.</dd></dl> + +<dl class="cmdoption"> +<dt id="cmdoption-sip-I"> +<tt class="descname">-I</tt><tt class="descclassname"> <DIR></tt><a class="headerlink" href="#cmdoption-sip-I" title="Permalink to this definition">¶</a></dt> +<dd>The directory is added to the list of directories searched when looking for +a specification file given in an <a class="reference external" href="directives.html#directive-%Include"><tt class="xref docutils literal"><span class="pre">%Include</span></tt></a> or +<a class="reference external" href="directives.html#directive-%Import"><tt class="xref docutils literal"><span class="pre">%Import</span></tt></a> directive. This option may be given any number of +times.</dd></dl> + +<dl class="cmdoption"> +<dt id="cmdoption-sip-j"> +<tt class="descname">-j</tt><tt class="descclassname"> <NUMBER></tt><a class="headerlink" href="#cmdoption-sip-j" title="Permalink to this definition">¶</a></dt> +<dd>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 +<tt class="docutils literal"><span class="pre">make</span></tt>. By default 1 file is generated for each C structure or C++ +class.</dd></dl> + +<dl class="cmdoption"> +<dt id="cmdoption-sip-k"> +<tt class="descname">-k</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-sip-k" title="Permalink to this definition">¶</a></dt> +<dd><p> +<span class="versionmodified">New in version 4.10.</span></p> +<p>All functions and methods will, by default, support passing parameters +using the Python keyword argument syntax.</p> +</dd></dl> + +<dl class="cmdoption"> +<dt id="cmdoption-sip-o"> +<tt class="descname">-o</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-sip-o" title="Permalink to this definition">¶</a></dt> +<dd><p> +<span class="versionmodified">New in version 4.10.</span></p> +<p>Docstrings will be automatically generated that describe the signature of +all functions, methods and constructors.</p> +</dd></dl> + +<dl class="cmdoption"> +<dt id="cmdoption-sip-p"> +<tt class="descname">-p</tt><tt class="descclassname"> <MODULE></tt><a class="headerlink" href="#cmdoption-sip-p" title="Permalink to this definition">¶</a></dt> +<dd>The name of the <a class="reference external" href="directives.html#directive-%ConsolidatedModule"><tt class="xref docutils literal"><span class="pre">%ConsolidatedModule</span></tt></a> which will contain the +wrapper code for this component module.</dd></dl> + +<dl class="cmdoption"> +<dt id="cmdoption-sip-P"> +<tt class="descname">-P</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-sip-P" title="Permalink to this definition">¶</a></dt> +<dd><p> +<span class="versionmodified">New in version 4.10.</span></p> +<p>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 <tt class="docutils literal"><span class="pre">protected</span></tt> keyword is redefined as <tt class="docutils literal"><span class="pre">public</span></tt> +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.</p> +</dd></dl> + +<dl class="cmdoption"> +<dt id="cmdoption-sip-r"> +<tt class="descname">-r</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-sip-r" title="Permalink to this definition">¶</a></dt> +<dd>Debugging statements that trace the execution of the bindings are +automatically generated. By default the statements are not generated.</dd></dl> + +<dl class="cmdoption"> +<dt id="cmdoption-sip-s"> +<tt class="descname">-s</tt><tt class="descclassname"> <SUFFIX></tt><a class="headerlink" href="#cmdoption-sip-s" title="Permalink to this definition">¶</a></dt> +<dd>The suffix to use for generated C or C++ source files. By default <tt class="docutils literal"><span class="pre">.c</span></tt> +is used for C and <tt class="docutils literal"><span class="pre">.cpp</span></tt> for C++.</dd></dl> + +<dl class="cmdoption"> +<dt id="cmdoption-sip-t"> +<tt class="descname">-t</tt><tt class="descclassname"> <TAG></tt><a class="headerlink" href="#cmdoption-sip-t" title="Permalink to this definition">¶</a></dt> +<dd>The SIP version tag (declared using a <a class="reference external" href="directives.html#directive-%Timeline"><tt class="xref docutils literal"><span class="pre">%Timeline</span></tt></a> directive) or +the SIP platform tag (declared using the <a class="reference external" href="directives.html#directive-%Platforms"><tt class="xref docutils literal"><span class="pre">%Platforms</span></tt></a> directive) +to generate code for. This option may be given any number of times so long +as the tags do not conflict.</dd></dl> + +<dl class="cmdoption"> +<dt id="cmdoption-sip-w"> +<tt class="descname">-w</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-sip-w" title="Permalink to this definition">¶</a></dt> +<dd>The display of warning messages is enabled. By default warning messages +are disabled.</dd></dl> + +<dl class="cmdoption"> +<dt id="cmdoption-sip-x"> +<tt class="descname">-x</tt><tt class="descclassname"> <FEATURE></tt><a class="headerlink" href="#cmdoption-sip-x" title="Permalink to this definition">¶</a></dt> +<dd>The feature (declared using the <a class="reference external" href="directives.html#directive-%Feature"><tt class="xref docutils literal"><span class="pre">%Feature</span></tt></a> directive) is +disabled.</dd></dl> + +<dl class="cmdoption"> +<dt id="cmdoption-sip-z"> +<tt class="descname">-z</tt><tt class="descclassname"> <FILE></tt><a class="headerlink" href="#cmdoption-sip-z" title="Permalink to this definition">¶</a></dt> +<dd>The name of a file containing more command line options.</dd></dl> + +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h4>Previous topic</h4> + <p class="topless"><a href="using.html" + title="previous chapter">Using SIP</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="specification_files.html" + title="next chapter">SIP Specification Files</a></p> + <div id="searchbox" style="display: none"> + <h3>Quick search</h3> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" size="18" /> + <input type="submit" value="Go" /> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </form> + <p class="searchtip" style="font-size: 90%"> + Enter search terms or a module, class or function name. + </p> + </div> + <script type="text/javascript">$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="modindex.html" title="Global Module Index" + >modules</a> |</li> + <li class="right" > + <a href="specification_files.html" title="SIP Specification Files" + >next</a> |</li> + <li class="right" > + <a href="using.html" title="Using SIP" + >previous</a> |</li> + <li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2010 Riverbank Computing Limited. + Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.4. + </div> + </body> +</html>
\ No newline at end of file diff --git a/doc/html/directives.html b/doc/html/directives.html new file mode 100644 index 0000000..eab1185 --- /dev/null +++ b/doc/html/directives.html @@ -0,0 +1,2045 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + + <title>Directives — SIP 4.10.5 Reference Guide</title> + <link rel="stylesheet" href="_static/default.css" type="text/css" /> + <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '#', + VERSION: '4.10.5', + COLLAPSE_MODINDEX: false, + FILE_SUFFIX: '.html', + HAS_SOURCE: true + }; + </script> + <script type="text/javascript" src="_static/jquery.js"></script> + <script type="text/javascript" src="_static/doctools.js"></script> + <link rel="top" title="SIP 4.10.5 Reference Guide" href="index.html" /> + <link rel="next" title="Annotations" href="annotations.html" /> + <link rel="prev" title="SIP Specification Files" href="specification_files.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="modindex.html" title="Global Module Index" + accesskey="M">modules</a> |</li> + <li class="right" > + <a href="annotations.html" title="Annotations" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="specification_files.html" title="SIP Specification Files" + accesskey="P">previous</a> |</li> + <li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="directives"> +<h1>Directives<a class="headerlink" href="#directives" title="Permalink to this headline">¶</a></h1> +<p>In this section we describe each of the directives that can be used in +specification files. All directives begin with <tt class="docutils literal"><span class="pre">%</span></tt> as the first +non-whitespace character in a line.</p> +<p>Some directives have arguments or contain blocks of code or documentation. In +the following descriptions these are shown in <em>italics</em>. Optional arguments +are enclosed in [<em>brackets</em>].</p> +<p>Some directives are used to specify handwritten code. Handwritten code must +not define names that start with the prefix <tt class="docutils literal"><span class="pre">sip</span></tt>.</p> +<dl class="directive"> +<dt id="directive-%AccessCode"> +<tt class="descname">%AccessCode</tt><a class="headerlink" href="#directive-%AccessCode" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%AccessCode + <em>code</em> +%End +</pre> +<p>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.</p> +<p>For example:</p> +<div class="highlight-python"><pre>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</pre> +</div> +<dl class="directive"> +<dt id="directive-%API"> +<tt class="descname">%API</tt><a class="headerlink" href="#directive-%API" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<p> +<span class="versionmodified">New in version 4.9.</span></p> +<pre class="literal-block"> +%API <em>name</em> <em>version</em> +</pre> +<p>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.</p> +<p>See <a class="reference external" href="using.html#ref-incompat-apis"><em>Managing Incompatible APIs</em></a> for more detail.</p> +<p>For example:</p> +<div class="highlight-python"><pre>%API PyQt4 1</pre> +</div> +<dl class="directive"> +<dt id="directive-%BIGetBufferCode"> +<tt class="descname">%BIGetBufferCode</tt><a class="headerlink" href="#directive-%BIGetBufferCode" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%BIGetBufferCode + <em>code</em> +%End +</pre> +<p>This directive (along with <a class="reference internal" href="#directive-%BIReleaseBufferCode"><tt class="xref docutils literal"><span class="pre">%BIReleaseBufferCode</span></tt></a>) is used to +specify code that implements the buffer interface of Python v3. If Python v2 +is being used then this is ignored.</p> +<p>The following variables are made available to the handwritten code:</p> +<dl class="docutils"> +<dt>Py_buffer *sipBuffer</dt> +<dd>This is a pointer to the Python buffer structure that the handwritten code +must populate.</dd> +<dt><em>type</em> *sipCpp</dt> +<dd>This is a pointer to the structure or class instance. Its <em>type</em> is a +pointer to the structure or class.</dd> +<dt>int sipFlags</dt> +<dd>These are the flags that specify what elements of the <tt class="docutils literal"><span class="pre">sipBuffer</span></tt> +structure must be populated.</dd> +<dt>int sipRes</dt> +<dd>The handwritten code should set this to 0 if there was no error or -1 if +there was an error.</dd> +<dt>PyObject *sipSelf</dt> +<dd>This is the Python object that wraps the structure or class instance, i.e. +<tt class="docutils literal"><span class="pre">self</span></tt>.</dd> +</dl> +<dl class="directive"> +<dt id="directive-%BIGetCharBufferCode"> +<tt class="descname">%BIGetCharBufferCode</tt><a class="headerlink" href="#directive-%BIGetCharBufferCode" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%BIGetCharBufferCode + <em>code</em> +%End +</pre> +<p>This directive (along with <a class="reference internal" href="#directive-%BIGetReadBufferCode"><tt class="xref docutils literal"><span class="pre">%BIGetReadBufferCode</span></tt></a>, +<a class="reference internal" href="#directive-%BIGetSegCountCode"><tt class="xref docutils literal"><span class="pre">%BIGetSegCountCode</span></tt></a> and <a class="reference internal" href="#directive-%BIGetWriteBufferCode"><tt class="xref docutils literal"><span class="pre">%BIGetWriteBufferCode</span></tt></a>) is used +to specify code that implements the buffer interface of Python v2. If Python +v3 is being used then this is ignored.</p> +<p>The following variables are made available to the handwritten code:</p> +<dl class="docutils"> +<dt><em>type</em> *sipCpp</dt> +<dd>This is a pointer to the structure or class instance. Its <em>type</em> is a +pointer to the structure or class.</dd> +<dt>void **sipPtrPtr</dt> +<dd>This is the pointer used to return the address of the character buffer.</dd> +<dt><a title="SIP_SSIZE_T" class="reference external" href="c_api.html#SIP_SSIZE_T"><tt class="xref docutils literal"><span class="pre">SIP_SSIZE_T</span></tt></a> sipRes</dt> +<dd>The handwritten code should set this to the length of the character buffer +or -1 if there was an error.</dd> +<dt><a title="SIP_SSIZE_T" class="reference external" href="c_api.html#SIP_SSIZE_T"><tt class="xref docutils literal"><span class="pre">SIP_SSIZE_T</span></tt></a> sipSegment</dt> +<dd>This is the number of the segment of the character buffer.</dd> +<dt>PyObject *sipSelf</dt> +<dd>This is the Python object that wraps the structure or class instance, i.e. +<tt class="docutils literal"><span class="pre">self</span></tt>.</dd> +</dl> +<dl class="directive"> +<dt id="directive-%BIGetReadBufferCode"> +<tt class="descname">%BIGetReadBufferCode</tt><a class="headerlink" href="#directive-%BIGetReadBufferCode" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%BIGetReadBufferCode + <em>code</em> +%End +</pre> +<p>This directive (along with <a class="reference internal" href="#directive-%BIGetCharBufferCode"><tt class="xref docutils literal"><span class="pre">%BIGetCharBufferCode</span></tt></a>, +<a class="reference internal" href="#directive-%BIGetSegCountCode"><tt class="xref docutils literal"><span class="pre">%BIGetSegCountCode</span></tt></a> and <a class="reference internal" href="#directive-%BIGetWriteBufferCode"><tt class="xref docutils literal"><span class="pre">%BIGetWriteBufferCode</span></tt></a>) is used +to specify code that implements the buffer interface of Python v2. If +Python v3 is being used then this is ignored.</p> +<p>The following variables are made available to the handwritten code:</p> +<dl class="docutils"> +<dt><em>type</em> *sipCpp</dt> +<dd>This is a pointer to the structure or class instance. Its <em>type</em> is a +pointer to the structure or class.</dd> +<dt>void **sipPtrPtr</dt> +<dd>This is the pointer used to return the address of the read buffer.</dd> +<dt><a title="SIP_SSIZE_T" class="reference external" href="c_api.html#SIP_SSIZE_T"><tt class="xref docutils literal"><span class="pre">SIP_SSIZE_T</span></tt></a> sipRes</dt> +<dd>The handwritten code should set this to the length of the read buffer or +-1 if there was an error.</dd> +<dt><a title="SIP_SSIZE_T" class="reference external" href="c_api.html#SIP_SSIZE_T"><tt class="xref docutils literal"><span class="pre">SIP_SSIZE_T</span></tt></a> sipSegment</dt> +<dd>This is the number of the segment of the read buffer.</dd> +<dt>PyObject *sipSelf</dt> +<dd>This is the Python object that wraps the structure or class instance, i.e. +<tt class="docutils literal"><span class="pre">self</span></tt>.</dd> +</dl> +<dl class="directive"> +<dt id="directive-%BIGetSegCountCode"> +<tt class="descname">%BIGetSegCountCode</tt><a class="headerlink" href="#directive-%BIGetSegCountCode" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%BIGetSegCountCode + <em>code</em> +%End +</pre> +<p>This directive (along with <a class="reference internal" href="#directive-%BIGetCharBufferCode"><tt class="xref docutils literal"><span class="pre">%BIGetCharBufferCode</span></tt></a>, +<a class="reference internal" href="#directive-%BIGetReadBufferCode"><tt class="xref docutils literal"><span class="pre">%BIGetReadBufferCode</span></tt></a> and <a class="reference internal" href="#directive-%BIGetWriteBufferCode"><tt class="xref docutils literal"><span class="pre">%BIGetWriteBufferCode</span></tt></a>) is +used to specify code that implements the buffer interface of Python v2. If +Python v3 is being used then this is ignored.</p> +<p>The following variables are made available to the handwritten code:</p> +<dl class="docutils"> +<dt><em>type</em> *sipCpp</dt> +<dd>This is a pointer to the structure or class instance. Its <em>type</em> is a +pointer to the structure or class.</dd> +<dt><a title="SIP_SSIZE_T" class="reference external" href="c_api.html#SIP_SSIZE_T"><tt class="xref docutils literal"><span class="pre">SIP_SSIZE_T</span></tt></a> *sipLenPtr</dt> +<dd>This is the pointer used to return the total length in bytes of all +segments of the buffer.</dd> +<dt><a title="SIP_SSIZE_T" class="reference external" href="c_api.html#SIP_SSIZE_T"><tt class="xref docutils literal"><span class="pre">SIP_SSIZE_T</span></tt></a> sipRes</dt> +<dd>The handwritten code should set this to the number of segments that make +up the buffer.</dd> +<dt>PyObject *sipSelf</dt> +<dd>This is the Python object that wraps the structure or class instance, i.e. +<tt class="docutils literal"><span class="pre">self</span></tt>.</dd> +</dl> +<dl class="directive"> +<dt id="directive-%BIGetWriteBufferCode"> +<tt class="descname">%BIGetWriteBufferCode</tt><a class="headerlink" href="#directive-%BIGetWriteBufferCode" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%BIGetWriteBufferCode + <em>code</em> +%End +</pre> +<p>This directive (along with <a class="reference internal" href="#directive-%BIGetCharBufferCode"><tt class="xref docutils literal"><span class="pre">%BIGetCharBufferCode</span></tt></a>, +<a class="reference internal" href="#directive-%BIGetReadBufferCode"><tt class="xref docutils literal"><span class="pre">%BIGetReadBufferCode</span></tt></a> and <a class="reference internal" href="#directive-%BIGetSegCountCode"><tt class="xref docutils literal"><span class="pre">%BIGetSegCountCode</span></tt></a> is used +to specify code that implements the buffer interface of Python v2. If Python +v3 is being used then this is ignored.</p> +<p>The following variables are made available to the handwritten code:</p> +<dl class="docutils"> +<dt><em>type</em> *sipCpp</dt> +<dd>This is a pointer to the structure or class instance. Its <em>type</em> is a +pointer to the structure or class.</dd> +<dt>void **sipPtrPtr</dt> +<dd>This is the pointer used to return the address of the write buffer.</dd> +<dt><a title="SIP_SSIZE_T" class="reference external" href="c_api.html#SIP_SSIZE_T"><tt class="xref docutils literal"><span class="pre">SIP_SSIZE_T</span></tt></a> sipRes</dt> +<dd>The handwritten code should set this to the length of the write buffer or +-1 if there was an error.</dd> +<dt><a title="SIP_SSIZE_T" class="reference external" href="c_api.html#SIP_SSIZE_T"><tt class="xref docutils literal"><span class="pre">SIP_SSIZE_T</span></tt></a> sipSegment</dt> +<dd>This is the number of the segment of the write buffer.</dd> +<dt>PyObject *sipSelf</dt> +<dd>This is the Python object that wraps the structure or class instance, i.e. +<tt class="docutils literal"><span class="pre">self</span></tt>.</dd> +</dl> +<dl class="directive"> +<dt id="directive-%BIReleaseBufferCode"> +<tt class="descname">%BIReleaseBufferCode</tt><a class="headerlink" href="#directive-%BIReleaseBufferCode" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%BIReleaseBufferCode + <em>code</em> +%End +</pre> +<p>This directive (along with <a class="reference internal" href="#directive-%BIGetBufferCode"><tt class="xref docutils literal"><span class="pre">%BIGetBufferCode</span></tt></a>) is used to specify +code that implements the buffer interface of Python v3. If Python v2 is being +used then this is ignored.</p> +<p>The following variables are made available to the handwritten code:</p> +<dl class="docutils"> +<dt>Py_buffer *sipBuffer</dt> +<dd>This is a pointer to the Python buffer structure.</dd> +<dt><em>type</em> *sipCpp</dt> +<dd>This is a pointer to the structure or class instance. Its <em>type</em> is a +pointer to the structure or class.</dd> +<dt>PyObject *sipSelf</dt> +<dd>This is the Python object that wraps the structure or class instance, i.e. +<tt class="docutils literal"><span class="pre">self</span></tt>.</dd> +</dl> +<dl class="directive"> +<dt id="directive-%CModule"> +<tt class="descname">%CModule</tt><a class="headerlink" href="#directive-%CModule" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%CModule <em>name</em> [<em>version</em>] +</pre> +<p>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.</p> +<p>See the <a class="reference internal" href="#directive-%Module"><tt class="xref docutils literal"><span class="pre">%Module</span></tt></a> directive for an explanation of the version +number.</p> +<p>For example:</p> +<div class="highlight-python"><pre>%CModule dbus 1</pre> +</div> +<dl class="directive"> +<dt id="directive-%CompositeModule"> +<tt class="descname">%CompositeModule</tt><a class="headerlink" href="#directive-%CompositeModule" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%CompositeModule <em>name</em> +</pre> +<p>A composite module is one that merges a number of related SIP generated +modules. For example, a module that merges the modules <tt class="docutils literal"><span class="pre">a_mod</span></tt>, <tt class="docutils literal"><span class="pre">b_mod</span></tt> +and <tt class="docutils literal"><span class="pre">c_mod</span></tt> is equivalent to the following pure Python module:</p> +<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">a_mod</span> <span class="kn">import</span> <span class="o">*</span> +<span class="kn">from</span> <span class="nn">b_mod</span> <span class="kn">import</span> <span class="o">*</span> +<span class="kn">from</span> <span class="nn">c_mod</span> <span class="kn">import</span> <span class="o">*</span> +</pre></div> +</div> +<p>Clearly the individual modules should not define module-level objects with the +same name.</p> +<p>This directive is used to specify the name of a composite module. Any +subsequent <a class="reference internal" href="#directive-%CModule"><tt class="xref docutils literal"><span class="pre">%CModule</span></tt></a> or <a class="reference internal" href="#directive-%Module"><tt class="xref docutils literal"><span class="pre">%Module</span></tt></a> directive is +interpreted as defining a component module.</p> +<p>For example:</p> +<div class="highlight-python"><pre>%CompositeModule PyQt4.Qt +%Include QtCore/QtCoremod.sip +%Include QtGui/QtGuimod.sip</pre> +</div> +<p>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.</p> +<dl class="directive"> +<dt id="directive-%ConsolidatedModule"> +<tt class="descname">%ConsolidatedModule</tt><a class="headerlink" href="#directive-%ConsolidatedModule" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%ConsolidatedModule <em>name</em> +</pre> +<p>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).</p> +<p>This directive is used to specify the name of a consolidated module. Any +subsequent <a class="reference internal" href="#directive-%CModule"><tt class="xref docutils literal"><span class="pre">%CModule</span></tt></a> or <a class="reference internal" href="#directive-%Module"><tt class="xref docutils literal"><span class="pre">%Module</span></tt></a> directive is +interpreted as defining a component module.</p> +<p>For example:</p> +<div class="highlight-python"><pre>%ConsolidatedModule PyQt4._qt +%Include QtCore/QtCoremod.sip +%Include QtGui/QtGuimod.sip</pre> +</div> +<p>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.</p> +<p>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.</p> +<p>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 <tt class="docutils literal"><span class="pre">-p</span></tt> command line option should be used to +specify the name of the consolidated module.</p> +<dl class="directive"> +<dt id="directive-%ConvertFromTypeCode"> +<tt class="descname">%ConvertFromTypeCode</tt><a class="headerlink" href="#directive-%ConvertFromTypeCode" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%ConvertFromTypeCode + <em>code</em> +%End +</pre> +<p>This directive is used as part of the <a class="reference internal" href="#directive-%MappedType"><tt class="xref docutils literal"><span class="pre">%MappedType</span></tt></a> directive to +specify the handwritten code that converts an instance of a mapped type to a +Python object.</p> +<p>The following variables are made available to the handwritten code:</p> +<dl class="docutils"> +<dt><em>type</em> *sipCpp</dt> +<dd>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 <tt class="docutils literal"><span class="pre">Py_None</span></tt> is handled +before the handwritten code is called.</dd> +<dt>PyObject *sipTransferObj</dt> +<dd>This specifies any desired ownership changes to the returned object. If it +is <tt class="docutils literal"><span class="pre">NULL</span></tt> then the ownership should be left unchanged. If it is +<tt class="docutils literal"><span class="pre">Py_None</span></tt> then ownership should be transferred to Python. Otherwise +ownership should be transferred to C/C++ and the returned object associated +with <em>sipTransferObj</em>. 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.</dd> +</dl> +<p>The handwritten code must explicitly return a <tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt>. If there was an +error then a Python exception must be raised and <tt class="docutils literal"><span class="pre">NULL</span></tt> returned.</p> +<p>The following example converts a <tt class="docutils literal"><span class="pre">QList<QWidget</span> <span class="pre">*></span></tt> instance to a Python +list of <tt class="docutils literal"><span class="pre">QWidget</span></tt> instances:</p> +<div class="highlight-python"><pre>%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</pre> +</div> +<dl class="directive"> +<dt id="directive-%ConvertToSubClassCode"> +<tt class="descname">%ConvertToSubClassCode</tt><a class="headerlink" href="#directive-%ConvertToSubClassCode" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%ConvertToSubClassCode + <em>code</em> +%End +</pre> +<p>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.</p> +<p>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.</p> +<p>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.</p> +<p>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.</p> +<p>The following variables are made available to the handwritten code:</p> +<dl class="docutils"> +<dt><em>type</em> *sipCpp</dt> +<dd>This is a pointer to the C++ class instance.</dd> +<dt>void **sipCppRet</dt> +<dd>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 <tt class="docutils literal"><span class="pre">static_cast</span></tt>) +from the super-class to the sub-class.</dd> +<dt>const sipTypeDef *sipType</dt> +<dd>The handwritten code must set this to the SIP generated type structure +that corresponds to the class instance. (The type structure for class +<tt class="docutils literal"><span class="pre">Klass</span></tt> is <tt class="docutils literal"><span class="pre">sipType_Klass</span></tt>.) If the RTTI of the class instance isn’t +recognised then <tt class="docutils literal"><span class="pre">sipType</span></tt> must be set to <tt class="docutils literal"><span class="pre">NULL</span></tt>. The code doesn’t +have to recognise the exact class, only the most specific sub-class that +it can.</dd> +<dt>sipWrapperType *sipClass</dt> +<dd><p class="first">The handwritten code must set this to the SIP generated Python type object +that corresponds to the class instance. (The type object for class +<tt class="docutils literal"><span class="pre">Klass</span></tt> is <tt class="docutils literal"><span class="pre">sipClass_Klass</span></tt>.) If the RTTI of the class instance isn’t +recognised then <tt class="docutils literal"><span class="pre">sipClass</span></tt> must be set to <tt class="docutils literal"><span class="pre">NULL</span></tt>. The code doesn’t +have to recognise the exact class, only the most specific sub-class that +it can.</p> +<p class="last">This is deprecated from SIP v4.8. Instead you should use <tt class="docutils literal"><span class="pre">sipType</span></tt>.</p> +</dd> +</dl> +<p>The handwritten code must not explicitly return.</p> +<p>The following example shows the sub-class conversion code for <tt class="docutils literal"><span class="pre">QEvent</span></tt> based +class hierarchy in PyQt:</p> +<div class="highlight-python"><pre>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. + +};</pre> +</div> +<dl class="directive"> +<dt id="directive-%ConvertToTypeCode"> +<tt class="descname">%ConvertToTypeCode</tt><a class="headerlink" href="#directive-%ConvertToTypeCode" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%ConvertToTypeCode + <em>code</em> +%End +</pre> +<p>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 <a class="reference internal" href="#directive-%MappedType"><tt class="xref docutils literal"><span class="pre">%MappedType</span></tt></a> 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.</p> +<p>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 <tt class="docutils literal"><span class="pre">QString</span></tt> class to allow Python string objects and +unicode objects to be used wherever <tt class="docutils literal"><span class="pre">QString</span></tt> instances are expected.</p> +<p>The following variables are made available to the handwritten code:</p> +<dl class="docutils"> +<dt>int *sipIsErr</dt> +<dd>If this is <tt class="docutils literal"><span class="pre">NULL</span></tt> 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.</dd> +<dt>PyObject *sipPy</dt> +<dd>This is the Python object to be converted.</dd> +<dt><em>type</em> **sipCppPtr</dt> +<dd>This is a pointer through which the address of the mapped type instance (or +zero if appropriate) is returned. Its value is undefined if <tt class="docutils literal"><span class="pre">sipIsErr</span></tt> +is <tt class="docutils literal"><span class="pre">NULL</span></tt>.</dd> +<dt>PyObject *sipTransferObj</dt> +<dd>This specifies any desired ownership changes to <em>sipPy</em>. If it is <tt class="docutils literal"><span class="pre">NULL</span></tt> +then the ownership should be left unchanged. If it is <tt class="docutils literal"><span class="pre">Py_None</span></tt> then +ownership should be transferred to Python. Otherwise ownership should be +transferred to C/C++ and <em>sipPy</em> associated with <em>sipTransferObj</em>. The +code can choose to interpret these changes in any way.</dd> +</dl> +<p>The handwritten code must explicitly return an <tt class="docutils literal"><span class="pre">int</span></tt> the meaning of which +depends on the value of <tt class="docutils literal"><span class="pre">sipIsErr</span></tt>.</p> +<p>If <tt class="docutils literal"><span class="pre">sipIsErr</span></tt> is <tt class="docutils literal"><span class="pre">NULL</span></tt> 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.</p> +<p>If <tt class="docutils literal"><span class="pre">sipIsErr</span></tt> is not <tt class="docutils literal"><span class="pre">NULL</span></tt> then a combination of the following flags is +returned.</p> +<blockquote> +<ul class="simple"> +<li><tt class="xref docutils literal"><span class="pre">SIP_TEMPORARY</span></tt> is set to indicate that the returned instance +is a temporary and should be released to avoid a memory leak.</li> +<li><tt class="xref docutils literal"><span class="pre">SIP_DERIVED_CLASS</span></tt> is set to indicate that the type of the +returned instance is a derived class. See +<a class="reference external" href="c_api.html#ref-derived-classes"><em>Generated Derived Classes</em></a>.</li> +</ul> +</blockquote> +<p>The following example converts a Python list of <tt class="docutils literal"><span class="pre">QPoint</span></tt> instances to a +<tt class="docutils literal"><span class="pre">QList<QPoint></span></tt> instance:</p> +<div class="highlight-python"><pre>%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</pre> +</div> +<p>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 +<a title="sipCanConvertToType" class="reference external" href="c_api.html#sipCanConvertToType"><tt class="xref docutils literal"><span class="pre">sipCanConvertToType()</span></tt></a> to check the object type and +<a title="sipConvertToType" class="reference external" href="c_api.html#sipConvertToType"><tt class="xref docutils literal"><span class="pre">sipConvertToType()</span></tt></a> to convert the object. The +<a title="SIP_NO_CONVERTORS" class="reference external" href="c_api.html#SIP_NO_CONVERTORS"><tt class="xref docutils literal"><span class="pre">SIP_NO_CONVERTORS</span></tt></a> flag <em>must</em> be passed to both these functions to +prevent recursive calls to the handwritten code.</p> +<dl class="directive"> +<dt id="directive-%Copying"> +<tt class="descname">%Copying</tt><a class="headerlink" href="#directive-%Copying" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%Copying + <em>text</em> +%End +</pre> +<p>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.</p> +<p>For example:</p> +<div class="highlight-python"><pre>%Copying +Copyright (c) 2009 Riverbank Computing Limited +%End</pre> +</div> +<dl class="directive"> +<dt id="directive-%DefaultEncoding"> +<tt class="descname">%DefaultEncoding</tt><a class="headerlink" href="#directive-%DefaultEncoding" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%DefaultEncoding <em>string</em> +</pre> +<p>This directive is used to specify the default encoding used for <tt class="docutils literal"><span class="pre">char</span></tt>, +<tt class="docutils literal"><span class="pre">const</span> <span class="pre">char</span></tt>, <tt class="docutils literal"><span class="pre">char</span> <span class="pre">*</span></tt> or <tt class="docutils literal"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></tt> values. The encoding can be +either <tt class="docutils literal"><span class="pre">"ASCII"</span></tt>, <tt class="docutils literal"><span class="pre">"Latin-1"</span></tt>, <tt class="docutils literal"><span class="pre">"UTF-8"</span></tt> or <tt class="docutils literal"><span class="pre">"None"</span></tt>. An encoding of +<tt class="docutils literal"><span class="pre">"None"</span></tt> means that the value is unencoded. The default can be overridden +for a particular value using the <a class="reference external" href="annotations.html#aanno-Encoding"><tt class="xref docutils literal"><span class="pre">Encoding</span></tt></a> annotation. If the +directive is not specified then <tt class="docutils literal"><span class="pre">"None"</span></tt> is used.</p> +<p>For example:</p> +<div class="highlight-python"><pre>%DefaultEncoding "Latin-1"</pre> +</div> +<dl class="directive"> +<dt id="directive-%DefaultMetatype"> +<tt class="descname">%DefaultMetatype</tt><a class="headerlink" href="#directive-%DefaultMetatype" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%DefaultMetatype <em>dotted-name</em> +</pre> +<p>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.</p> +<p>If this is not specified then <tt class="docutils literal"><span class="pre">sip.wrappertype</span></tt> is used.</p> +<p>You can also use the <a class="reference external" href="annotations.html#canno-Metatype"><tt class="xref docutils literal"><span class="pre">Metatype</span></tt></a> class annotation to specify the +meta-type used by a particular C/C++ type.</p> +<p>See the section <a class="reference external" href="using.html#ref-types-metatypes"><em>Types and Meta-types</em></a> for more details.</p> +<p>For example:</p> +<div class="highlight-python"><pre>%DefaultMetatype PyQt4.QtCore.pyqtWrapperType</pre> +</div> +<dl class="directive"> +<dt id="directive-%DefaultSupertype"> +<tt class="descname">%DefaultSupertype</tt><a class="headerlink" href="#directive-%DefaultSupertype" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%DefaultSupertype <em>dotted-name</em> +</pre> +<p>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.</p> +<p>If this is not specified then <tt class="docutils literal"><span class="pre">sip.wrapper</span></tt> is used.</p> +<p>You can also use the <a class="reference external" href="annotations.html#canno-Supertype"><tt class="xref docutils literal"><span class="pre">Supertype</span></tt></a> class annotation to specify the +super-type used by a particular C/C++ type.</p> +<p>See the section <a class="reference external" href="using.html#ref-types-metatypes"><em>Types and Meta-types</em></a> for more details.</p> +<p>For example:</p> +<div class="highlight-python"><pre>%DefaultSupertype sip.simplewrapper</pre> +</div> +<dl class="directive"> +<dt id="directive-%Doc"> +<tt class="descname">%Doc</tt><a class="headerlink" href="#directive-%Doc" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%Doc + <em>text</em> +%End +</pre> +<p>This directive is used to specify some arbitrary text that will be extracted +by SIP when the <tt class="docutils literal"><span class="pre">-d</span></tt> 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.</p> +<p>Documentation that is specified using this directive is local to the module in +which it appears. It is ignored by modules that <a class="reference internal" href="#directive-%Import"><tt class="xref docutils literal"><span class="pre">%Import</span></tt></a> it. Use +the <a class="reference internal" href="#directive-%ExportedDoc"><tt class="xref docutils literal"><span class="pre">%ExportedDoc</span></tt></a> directive for documentation that should be +included by all modules that <a class="reference internal" href="#directive-%Import"><tt class="xref docutils literal"><span class="pre">%Import</span></tt></a> this one.</p> +<p>For example:</p> +<div class="highlight-python"><pre>%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</pre> +</div> +<dl class="directive"> +<dt id="directive-%Docstring"> +<tt class="descname">%Docstring</tt><a class="headerlink" href="#directive-%Docstring" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%Docstring + <em>text</em> +%End +</pre> +<p> +<span class="versionmodified">New in version 4.10.</span></p> +<p>This directive is used to specify explicit docstrings for classes, functions +and methods.</p> +<p>The docstring of a class is made up of the docstring specified for the class +itself, with the docstrings specified for each contructor appended.</p> +<p>The docstring of a function or method is made up of the concatenated docstrings +specified for each of the overloads.</p> +<p>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.</p> +<p>For example:</p> +<div class="highlight-python"><pre>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 +};</pre> +</div> +<dl class="directive"> +<dt id="directive-%End"> +<tt class="descname">%End</tt><a class="headerlink" href="#directive-%End" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<p>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.</p> +<dl class="directive"> +<dt id="directive-%Exception"> +<tt class="descname">%Exception</tt><a class="headerlink" href="#directive-%Exception" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%Exception <em>name</em> [(<em>base-exception)] +{ + [*header-code</em>] + <em>raise-code</em> +}; +</pre> +<p>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 <tt class="docutils literal"><span class="pre">throw</span> <span class="pre">()</span></tt> specifiers must either be names of classes or the +names of Python exceptions defined by this directive.</p> +<p><em>name</em> is the name of the exception.</p> +<p><em>base-exception</em> is the optional base exception. This may be either one of +the standard Python exceptions or one defined with a previous +<a class="reference internal" href="#directive-%Exception"><tt class="xref docutils literal"><span class="pre">%Exception</span></tt></a> directive.</p> +<p><em>header-code</em> is the optional <a class="reference internal" href="#directive-%TypeHeaderCode"><tt class="xref docutils literal"><span class="pre">%TypeHeaderCode</span></tt></a> used to specify any +external interface to the exception being defined.</p> +<p><em>raise-code</em> is the <a class="reference internal" href="#directive-%RaiseCode"><tt class="xref docutils literal"><span class="pre">%RaiseCode</span></tt></a> used to specify the handwritten +code that converts a reference to the C++ exception to the Python exception.</p> +<p>For example:</p> +<div class="highlight-python"><pre>%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 +};</pre> +</div> +<p>In this example we map the standard C++ exception to a new Python exception. +The new exception is called <tt class="docutils literal"><span class="pre">StdException</span></tt> and is derived from the standard +Python exception <tt class="docutils literal"><span class="pre">Exception</span></tt>.</p> +<p>An exception may be annotated with <a class="reference external" href="annotations.html#xanno-Default"><tt class="xref docutils literal"><span class="pre">Default</span></tt></a> to specify that it should +be caught by default if there is no <tt class="docutils literal"><span class="pre">throw</span></tt> clause.</p> +<dl class="directive"> +<dt id="directive-%ExportedDoc"> +<tt class="descname">%ExportedDoc</tt><a class="headerlink" href="#directive-%ExportedDoc" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%ExportedDoc + <em>text</em> +%End +</pre> +<p>This directive is used to specify some arbitrary text that will be extracted +by SIP when the <tt class="docutils literal"><span class="pre">-d</span></tt> 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.</p> +<p>Documentation that is specified using this directive will also be included by +modules that <a class="reference internal" href="#directive-%Import"><tt class="xref docutils literal"><span class="pre">%Import</span></tt></a> it.</p> +<p>For example:</p> +<div class="highlight-python"><pre>%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</pre> +</div> +<dl class="directive"> +<dt id="directive-%ExportedHeaderCode"> +<tt class="descname">%ExportedHeaderCode</tt><a class="headerlink" href="#directive-%ExportedHeaderCode" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%ExportedHeaderCode + <em>code</em> +%End +</pre> +<p>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.</p> +<p>See also <a class="reference internal" href="#directive-%ModuleCode"><tt class="xref docutils literal"><span class="pre">%ModuleCode</span></tt></a> and <a class="reference internal" href="#directive-%ModuleHeaderCode"><tt class="xref docutils literal"><span class="pre">%ModuleHeaderCode</span></tt></a>.</p> +<dl class="directive"> +<dt id="directive-%Feature"> +<tt class="descname">%Feature</tt><a class="headerlink" href="#directive-%Feature" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%Feature <em>name</em> +</pre> +<p>This directive is used to declare a feature. Features (along with +<a class="reference internal" href="#directive-%Platforms"><tt class="xref docutils literal"><span class="pre">%Platforms</span></tt></a> and <a class="reference internal" href="#directive-%Timeline"><tt class="xref docutils literal"><span class="pre">%Timeline</span></tt></a>) are used by the +<a class="reference internal" href="#directive-%If"><tt class="xref docutils literal"><span class="pre">%If</span></tt></a> directive to control whether or not parts of a specification +are processed or ignored.</p> +<p>Features are mutually independent of each other - any combination of features +may be enabled or disable. By default all features are enabled. The SIP +<tt class="docutils literal"><span class="pre">-x</span></tt> command line option is used to disable a feature.</p> +<p>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 <tt class="docutils literal"><span class="pre">SIP_FEATURE_</span></tt>.</p> +<p>For example:</p> +<div class="highlight-python"><pre>%Feature FOO_SUPPORT + +%If (FOO_SUPPORT) +void foo(); +%End</pre> +</div> +<dl class="directive"> +<dt id="directive-%GCClearCode"> +<tt class="descname">%GCClearCode</tt><a class="headerlink" href="#directive-%GCClearCode" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%GCClearCode + <em>code</em> +%End +</pre> +<p>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.</p> +<p>See the section <em>Supporting cyclic garbage collection</em> in <a class="reference external" href="http://www.python.org/dev/doc/devel/ext/">Embedding and +Extending the Python Interpreter</a> +for the details.</p> +<p>This directive is used to specify the code that clears any embedded references. +(See <a class="reference internal" href="#directive-%GCTraverseCode"><tt class="xref docutils literal"><span class="pre">%GCTraverseCode</span></tt></a> for specifying the code that traverses any +embedded references.)</p> +<p>The following variables are made available to the handwritten code:</p> +<dl class="docutils"> +<dt><em>type</em> *sipCpp</dt> +<dd>This is a pointer to the structure or class instance. Its <em>type</em> is a +pointer to the structure or class.</dd> +<dt>int sipRes</dt> +<dd>The handwritten code should set this to the result to be returned.</dd> +</dl> +<p>The following simplified example is taken from PyQt. The <tt class="docutils literal"><span class="pre">QCustomEvent</span></tt> +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:</p> +<div class="highlight-python"><pre>%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</pre> +</div> +<dl class="directive"> +<dt id="directive-%GCTraverseCode"> +<tt class="descname">%GCTraverseCode</tt><a class="headerlink" href="#directive-%GCTraverseCode" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%GCTraverseCode + <em>code</em> +%End +</pre> +<p>This directive is used to specify the code that traverses any embedded +references for Python’s cyclic garbage collector. (See +<a class="reference internal" href="#directive-%GCClearCode"><tt class="xref docutils literal"><span class="pre">%GCClearCode</span></tt></a> for a full explanation.)</p> +<p>The following variables are made available to the handwritten code:</p> +<dl class="docutils"> +<dt><em>type</em> *sipCpp</dt> +<dd>This is a pointer to the structure or class instance. Its <em>type</em> is a +pointer to the structure or class.</dd> +<dt>visitproc sipVisit</dt> +<dd>This is the visit function provided by the garbage collector.</dd> +<dt>void *sipArg</dt> +<dd>This is the argument to the visit function provided by the garbage +collector.</dd> +<dt>int sipRes</dt> +<dd>The handwritten code should set this to the result to be returned.</dd> +</dl> +<p>The following simplified example is taken from PyQt’s <tt class="docutils literal"><span class="pre">QCustomEvent</span></tt> class:</p> +<div class="highlight-python"><pre>%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</pre> +</div> +<dl class="directive"> +<dt id="directive-%GetCode"> +<tt class="descname">%GetCode</tt><a class="headerlink" href="#directive-%GetCode" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%GetCode + <em>code</em> +%End +</pre> +<p>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.</p> +<p>The following variables are made available to the handwritten code:</p> +<dl class="docutils"> +<dt><em>type</em> *sipCpp</dt> +<dd>This is a pointer to the structure or class instance. Its <em>type</em> is a +pointer to the structure or class. It is not made available if the +variable being wrapped is a static class variable.</dd> +<dt>PyObject *sipPy</dt> +<dd>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 <tt class="docutils literal"><span class="pre">NULL</span></tt>.</dd> +<dt>PyObject *sipPyType</dt> +<dd>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 +(<em>not</em> the class in which it is defined). It may be safely cast to a +PyTypeObject * or a sipWrapperType *.</dd> +</dl> +<p>For example:</p> +<div class="highlight-python"><pre>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 +}</pre> +</div> +<dl class="directive"> +<dt id="directive-%If"> +<tt class="descname">%If</tt><a class="headerlink" href="#directive-%If" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%If (<em>expression</em>) + <em>specification</em> +%End +</pre> +<p>where</p> +<pre class="literal-block"> +<em>expression</em> ::= [<em>ored-qualifiers</em> | <em>range</em>] + +<em>ored-qualifiers</em> ::= [<em>qualifier</em> | <em>qualifier</em> <strong>||</strong> <em>ored-qualifiers</em>] + +<em>qualifier</em> ::= [<strong>!</strong>] [<em>feature</em> | <em>platform</em>] + +<em>range</em> ::= [<em>version</em>] <strong>-</strong> [<em>version</em>] +</pre> +<p>This directive is used in conjunction with features (see +<a class="reference internal" href="#directive-%Feature"><tt class="xref docutils literal"><span class="pre">%Feature</span></tt></a>), platforms (see <a class="reference internal" href="#directive-%Platforms"><tt class="xref docutils literal"><span class="pre">%Platforms</span></tt></a>) and versions +(see <a class="reference internal" href="#directive-%Timeline"><tt class="xref docutils literal"><span class="pre">%Timeline</span></tt></a>) to control whether or not parts of a specification +are processed or not.</p> +<p>A <em>range</em> 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.</p> +<p>For example:</p> +<div class="highlight-python"><pre>%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</pre> +</div> +<p>Note that this directive is not implemented as a preprocessor. Only the +following parts of a specification are affected by it:</p> +<blockquote> +<ul class="simple"> +<li><a class="reference internal" href="#directive-%API"><tt class="xref docutils literal"><span class="pre">%API</span></tt></a></li> +<li><tt class="docutils literal"><span class="pre">class</span></tt></li> +<li><a class="reference internal" href="#directive-%ConvertFromTypeCode"><tt class="xref docutils literal"><span class="pre">%ConvertFromTypeCode</span></tt></a></li> +<li><a class="reference internal" href="#directive-%ConvertToSubClassCode"><tt class="xref docutils literal"><span class="pre">%ConvertToSubClassCode</span></tt></a></li> +<li><a class="reference internal" href="#directive-%ConvertToTypeCode"><tt class="xref docutils literal"><span class="pre">%ConvertToTypeCode</span></tt></a></li> +<li><tt class="docutils literal"><span class="pre">enum</span></tt></li> +<li><a class="reference internal" href="#directive-%DefaultEncoding"><tt class="xref docutils literal"><span class="pre">%DefaultEncoding</span></tt></a></li> +<li><a class="reference internal" href="#directive-%DefaultMetatype"><tt class="xref docutils literal"><span class="pre">%DefaultMetatype</span></tt></a></li> +<li><a class="reference internal" href="#directive-%DefaultSupertype"><tt class="xref docutils literal"><span class="pre">%DefaultSupertype</span></tt></a></li> +<li><a class="reference internal" href="#directive-%ExportedHeaderCode"><tt class="xref docutils literal"><span class="pre">%ExportedHeaderCode</span></tt></a></li> +<li>functions</li> +<li><a class="reference internal" href="#directive-%GCClearCode"><tt class="xref docutils literal"><span class="pre">%GCClearCode</span></tt></a></li> +<li><a class="reference internal" href="#directive-%GCTraverseCode"><tt class="xref docutils literal"><span class="pre">%GCTraverseCode</span></tt></a></li> +<li><a class="reference internal" href="#directive-%If"><tt class="xref docutils literal"><span class="pre">%If</span></tt></a></li> +<li><a class="reference internal" href="#directive-%InitialisationCode"><tt class="xref docutils literal"><span class="pre">%InitialisationCode</span></tt></a></li> +<li><a class="reference internal" href="#directive-%MappedType"><tt class="xref docutils literal"><span class="pre">%MappedType</span></tt></a></li> +<li><a class="reference internal" href="#directive-%MethodCode"><tt class="xref docutils literal"><span class="pre">%MethodCode</span></tt></a></li> +<li><a class="reference internal" href="#directive-%ModuleCode"><tt class="xref docutils literal"><span class="pre">%ModuleCode</span></tt></a></li> +<li><a class="reference internal" href="#directive-%ModuleHeaderCode"><tt class="xref docutils literal"><span class="pre">%ModuleHeaderCode</span></tt></a></li> +<li><tt class="docutils literal"><span class="pre">namespace</span></tt></li> +<li><a class="reference internal" href="#directive-%PostInitialisationCode"><tt class="xref docutils literal"><span class="pre">%PostInitialisationCode</span></tt></a></li> +<li><a class="reference internal" href="#directive-%PreInitialisationCode"><tt class="xref docutils literal"><span class="pre">%PreInitialisationCode</span></tt></a></li> +<li><tt class="docutils literal"><span class="pre">struct</span></tt></li> +<li><tt class="docutils literal"><span class="pre">typedef</span></tt></li> +<li><a class="reference internal" href="#directive-%TypeCode"><tt class="xref docutils literal"><span class="pre">%TypeCode</span></tt></a></li> +<li><a class="reference internal" href="#directive-%TypeHeaderCode"><tt class="xref docutils literal"><span class="pre">%TypeHeaderCode</span></tt></a></li> +<li><a class="reference internal" href="#directive-%UnitCode"><tt class="xref docutils literal"><span class="pre">%UnitCode</span></tt></a></li> +<li>variables</li> +<li><a class="reference internal" href="#directive-%VirtualCatcherCode"><tt class="xref docutils literal"><span class="pre">%VirtualCatcherCode</span></tt></a></li> +</ul> +</blockquote> +<p>Also note that the only way to specify the logical and of qualifiers is to use +nested <a class="reference internal" href="#directive-%If"><tt class="xref docutils literal"><span class="pre">%If</span></tt></a> directives.</p> +<dl class="directive"> +<dt id="directive-%Import"> +<tt class="descname">%Import</tt><a class="headerlink" href="#directive-%Import" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%Import <em>filename</em> +</pre> +<p>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.</p> +<p>If <em>filename</em> cannot be opened then SIP prepends <em>filename</em> with the name of +the directory containing the current specification file (i.e. the one +containing the <a class="reference internal" href="#directive-%Import"><tt class="xref docutils literal"><span class="pre">%Import</span></tt></a> directive) and tries again. If this also +fails then SIP prepends <em>filename</em> with each of the directories, in turn, +specified by the <tt class="docutils literal"><span class="pre">-I</span></tt> command line option.</p> +<p>For example:</p> +<div class="highlight-python"><pre>%Import qt/qtmod.sip</pre> +</div> +<dl class="directive"> +<dt id="directive-%Include"> +<tt class="descname">%Include</tt><a class="headerlink" href="#directive-%Include" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%Include <em>filename</em> +</pre> +<p>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 <tt class="docutils literal"><span class="pre">#include</span></tt> directive and is used to structure a large module +specification into manageable pieces.</p> +<p><a class="reference internal" href="#directive-%Include"><tt class="xref docutils literal"><span class="pre">%Include</span></tt></a> follows the same search process as <a class="reference internal" href="#directive-%Import"><tt class="xref docutils literal"><span class="pre">%Import</span></tt></a> +when trying to open <em>filename</em>.</p> +<p>For example:</p> +<div class="highlight-python"><pre>%Include qwidget.sip</pre> +</div> +<dl class="directive"> +<dt id="directive-%InitialisationCode"> +<tt class="descname">%InitialisationCode</tt><a class="headerlink" href="#directive-%InitialisationCode" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%InitialisationCode + <em>code</em> +%End +</pre> +<p>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.</p> +<p>It is typically used to call <a title="sipRegisterPyType" class="reference external" href="c_api.html#sipRegisterPyType"><tt class="xref docutils literal"><span class="pre">sipRegisterPyType()</span></tt></a>.</p> +<p>For example:</p> +<div class="highlight-python"><pre>%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</pre> +</div> +<dl class="directive"> +<dt id="directive-%License"> +<tt class="descname">%License</tt><a class="headerlink" href="#directive-%License" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%License /<em>license-annotations</em>/ +</pre> +<p>This directive is used to specify the contents of an optional license +dictionary. The license dictionary is called <tt class="xref docutils literal"><span class="pre">__license__</span></tt> and is stored +in the module dictionary. The elements of the dictionary are specified using +the <a class="reference external" href="annotations.html#lanno-Licensee"><tt class="xref docutils literal"><span class="pre">Licensee</span></tt></a>, <a class="reference external" href="annotations.html#lanno-Signature"><tt class="xref docutils literal"><span class="pre">Signature</span></tt></a>, <a class="reference external" href="annotations.html#lanno-Timestamp"><tt class="xref docutils literal"><span class="pre">Timestamp</span></tt></a> and <a class="reference external" href="annotations.html#lanno-Type"><tt class="xref docutils literal"><span class="pre">Type</span></tt></a> +annotations. Only the <a class="reference external" href="annotations.html#lanno-Type"><tt class="xref docutils literal"><span class="pre">Type</span></tt></a> annotation is compulsory.</p> +<p>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.</p> +<p>For example:</p> +<div class="highlight-python"><pre>%License /Type="GPL"/</pre> +</div> +<dl class="directive"> +<dt id="directive-%MappedType"> +<tt class="descname">%MappedType</tt><a class="headerlink" href="#directive-%MappedType" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +template<<em>type-list</em>> +%MappedType <em>type</em> +{ + [<em>header-code</em>] + [<em>convert-to-code</em>] + [<em>convert-from-code</em>] +}; + +%MappedType <em>type</em> +{ + [<em>header-code</em>] + [<em>convert-to-code</em>] + [<em>convert-from-code</em>] +}; +</pre> +<p>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.</p> +<p>When used as part of a template <em>type</em> cannot itself refer to a template. Any +occurrences of any of the type names (but not any <tt class="docutils literal"><span class="pre">*</span></tt> or <tt class="docutils literal"><span class="pre">&</span></tt>) in +<em>type-list</em> 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 <tt class="docutils literal"><span class="pre">typedef</span></tt>).</p> +<p>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.</p> +<p><em>header-code</em> is the <a class="reference internal" href="#directive-%TypeHeaderCode"><tt class="xref docutils literal"><span class="pre">%TypeHeaderCode</span></tt></a> used to specify the library +interface to the type being mapped.</p> +<p><em>convert-to-code</em> is the <a class="reference internal" href="#directive-%ConvertToTypeCode"><tt class="xref docutils literal"><span class="pre">%ConvertToTypeCode</span></tt></a> used to specify the +handwritten code that converts a Python object to an instance of the mapped +type.</p> +<p><em>convert-from-code</em> is the <a class="reference internal" href="#directive-%ConvertFromTypeCode"><tt class="xref docutils literal"><span class="pre">%ConvertFromTypeCode</span></tt></a> used to specify +the handwritten code that converts an instance of the mapped type to a Python +object.</p> +<p>For example:</p> +<div class="highlight-python"><pre>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 +}</pre> +</div> +<p>Using this we can use, for example, <tt class="docutils literal"><span class="pre">QList<QObject</span> <span class="pre">*></span></tt> 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.</p> +<dl class="directive"> +<dt id="directive-%MethodCode"> +<tt class="descname">%MethodCode</tt><a class="headerlink" href="#directive-%MethodCode" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%MethodCode + <em>code</em> +%End +</pre> +<p>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.</p> +<p>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 <tt class="docutils literal"><span class="pre">return</span></tt> +statements.</p> +<p>However if the <a class="reference external" href="annotations.html#fanno-NoArgParser"><tt class="xref docutils literal"><span class="pre">NoArgParser</span></tt></a> 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 <tt class="docutils literal"><span class="pre">return</span></tt> statement.</p> +<p>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.</p> +<p>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:</p> +<div class="highlight-python"><pre>Py_BEGIN_ALLOW_THREADS +sipCpp->foo(); +Py_END_ALLOW_THREADS</pre> +</div> +<p>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 <a class="reference external" href="using.html#ref-gil"><em>The Python Global Interpreter Lock</em></a> and the +<a class="reference external" href="annotations.html#fanno-ReleaseGIL"><tt class="xref docutils literal"><span class="pre">ReleaseGIL</span></tt></a> and <a class="reference external" href="annotations.html#fanno-HoldGIL"><tt class="xref docutils literal"><span class="pre">HoldGIL</span></tt></a> annotations.)</p> +<p>If the <a class="reference external" href="annotations.html#fanno-NoArgParser"><tt class="xref docutils literal"><span class="pre">NoArgParser</span></tt></a> annotation has not been used then the following +variables are made available to the handwritten code:</p> +<dl class="docutils"> +<dt><em>type</em> a0</dt> +<dd><p class="first">There is a variable for each argument of the Python signature (excluding +any <tt class="docutils literal"><span class="pre">self</span></tt> argument) named <tt class="docutils literal"><span class="pre">a0</span></tt>, <tt class="docutils literal"><span class="pre">a1</span></tt>, etc. The <em>type</em> of the +variable is the same as the type defined in the specification with the +following exceptions:</p> +<ul class="simple"> +<li>if the argument is only used to return a value (e.g. it is an <tt class="docutils literal"><span class="pre">int</span> <span class="pre">*</span></tt> +without an <a class="reference external" href="annotations.html#aanno-In"><tt class="xref docutils literal"><span class="pre">In</span></tt></a> annotation) then the type has one less level of +indirection (e.g. it will be an <tt class="docutils literal"><span class="pre">int</span></tt>)</li> +<li>if the argument is a structure or class (or a reference or a pointer to a +structure or class) then <em>type</em> will always be a pointer to the structure +or class.</li> +</ul> +<p class="last">Note that handwritten code for destructors never has any arguments.</p> +</dd> +<dt>PyObject *a0Wrapper</dt> +<dd>This variable is made available only if the <a class="reference external" href="annotations.html#aanno-GetWrapper"><tt class="xref docutils literal"><span class="pre">GetWrapper</span></tt></a> annotation +is specified for the corresponding argument. The variable is a pointer to +the Python object that wraps the argument.</dd> +<dt><em>type</em> *sipCpp</dt> +<dd><p class="first">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 <tt class="docutils literal"><span class="pre">0</span></tt> and no Python exception is raised then SIP will continue to +try other Python signatures.</p> +<p>If the directive is used in the context of a method (but not the standard +binary operator methods, e.g. <tt class="xref docutils literal"><span class="pre">__add__()</span></tt>) or a destructor then this is +a pointer to the C structure or C++ class instance.</p> +<p>Its <em>type</em> is a pointer to the structure or class.</p> +<p class="last">Standard binary operator methods follow the same convention as global +functions and instead define two arguments called <tt class="docutils literal"><span class="pre">a0</span></tt> and <tt class="docutils literal"><span class="pre">a1</span></tt>.</p> +</dd> +<dt>sipErrorState sipError</dt> +<dd><p class="first">The handwritten code should set this to either <tt class="docutils literal"><span class="pre">sipErrorContinue</span></tt> or +<tt class="docutils literal"><span class="pre">sipErrorFail</span></tt>, and raise an appropriate Python exception, if an error +is detected. Its initial value will be <tt class="docutils literal"><span class="pre">sipErrorNone</span></tt>.</p> +<p>When <tt class="docutils literal"><span class="pre">sipErrorContinue</span></tt> 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.</p> +<p>When <tt class="docutils literal"><span class="pre">sipErrorFail1</span></tt> is used, SIP will report the exception immediately +and will not attempt to invoke other overloaded callables.</p> +<p class="last"><tt class="docutils literal"><span class="pre">sipError</span></tt> is not provided for destructors.</p> +</dd> +<dt>int sipIsErr</dt> +<dd><p class="first">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 <tt class="docutils literal"><span class="pre">sipError</span></tt> to <tt class="docutils literal"><span class="pre">sipErrorFail</span></tt>. Its initial value +will be <tt class="docutils literal"><span class="pre">0</span></tt>.</p> +<p class="last"><tt class="docutils literal"><span class="pre">sipIsErr</span></tt> is not provided for destructors.</p> +</dd> +<dt><em>type</em> sipRes</dt> +<dd><p class="first">The handwritten code should set this to the result to be returned. The +<em>type</em> of the variable is the same as the type defined in the Python +signature in the specification with the following exception:</p> +<ul class="simple"> +<li>if the argument is a structure or class (or a reference or a pointer to a +structure or class) then <em>type</em> will always be a pointer to the structure +or class.</li> +</ul> +<p class="last"><tt class="docutils literal"><span class="pre">sipRes</span></tt> is not provided for inplace operators (e.g. <tt class="docutils literal"><span class="pre">+=</span></tt> or +<tt class="xref docutils literal"><span class="pre">__imul__()</span></tt>) as their results are handled automatically, nor for class +constructors or destructors.</p> +</dd> +<dt>PyObject *sipSelf</dt> +<dd>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. <tt class="docutils literal"><span class="pre">self</span></tt>.</dd> +<dt>bool sipSelfWasArg</dt> +<dd><p class="first">This is only made available for non-abstract, virtual methods. It is set +if <tt class="docutils literal"><span class="pre">self</span></tt> was explicitly passed as the first argument of the method +rather than being bound to the method. In other words, the call was:</p> +<div class="highlight-python"><div class="highlight"><pre><span class="n">Klass</span><span class="o">.</span><span class="n">foo</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">...</span><span class="p">)</span> +</pre></div> +</div> +<p>rather than:</p> +<div class="last highlight-python"><div class="highlight"><pre><span class="bp">self</span><span class="o">.</span><span class="n">foo</span><span class="p">(</span><span class="o">...</span><span class="p">)</span> +</pre></div> +</div> +</dd> +</dl> +<p>If the <a class="reference external" href="annotations.html#fanno-NoArgParser"><tt class="xref docutils literal"><span class="pre">NoArgParser</span></tt></a> annotation has been used then only the following +variables are made available to the handwritten code:</p> +<dl class="docutils"> +<dt>PyObject *sipArgs</dt> +<dd>This is the tuple of arguments.</dd> +<dt>PyObject *sipKwds</dt> +<dd>This is the dictionary of keyword arguments.</dd> +</dl> +<p>The following is a complete example:</p> +<div class="highlight-python"><pre>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 +};</pre> +</div> +<p>As the example is a virtual method <a class="footnote-reference" href="#id2" id="id1">[1]</a>, note the use of <tt class="docutils literal"><span class="pre">sipSelfWasArg</span></tt> to +determine exactly which implementation of <tt class="docutils literal"><span class="pre">foo()</span></tt> to call.</p> +<p>If a method is in the <tt class="docutils literal"><span class="pre">protected</span></tt> 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 <tt class="docutils literal"><span class="pre">protected</span></tt> redefined as <tt class="docutils literal"><span class="pre">public</span></tt>.</p> +<p>The following pattern should be used to cover all possibilities:</p> +<div class="highlight-python"><pre>#if defined(SIP_PROTECTED_IS_PUBLIC) + sipRes = sipSelfWasArg ? sipCpp->Klass::foo(iarr) + : sipCpp->foo(iarr); +#else + sipRes = sipCpp->sipProtectVirt_foo(sipSelfWasArg, iarr); +#endif</pre> +</div> +<p>If a method is in the <tt class="docutils literal"><span class="pre">protected</span></tt> section of a C++ class but is not virtual +then the pattern should instead be:</p> +<div class="highlight-python"><pre>#if defined(SIP_PROTECTED_IS_PUBLIC) + sipRes = sipCpp->foo(iarr); +#else + sipRes = sipCpp->sipProtect_foo(iarr); +#endif</pre> +</div> +<table class="docutils footnote" frame="void" id="id2" rules="none"> +<colgroup><col class="label" /><col /></colgroup> +<tbody valign="top"> +<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>See <a class="reference internal" href="#directive-%VirtualCatcherCode"><tt class="xref docutils literal"><span class="pre">%VirtualCatcherCode</span></tt></a> for a description of how SIP +generated code handles the reimplementation of C++ virtual methods in +Python.</td></tr> +</tbody> +</table> +<dl class="directive"> +<dt id="directive-%Module"> +<tt class="descname">%Module</tt><a class="headerlink" href="#directive-%Module" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%Module <em>name</em> [<em>version</em>] +</pre> +<p>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.</p> +<p>The name may contain periods to specify that the module is part of a Python +package.</p> +<p>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 +<a class="reference internal" href="#directive-%Import"><tt class="xref docutils literal"><span class="pre">%Import</span></tt></a> this module. Under the covers, a module exports an API +that is used by modules that <a class="reference internal" href="#directive-%Import"><tt class="xref docutils literal"><span class="pre">%Import</span></tt></a> 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.</p> +<p>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.</p> +<p>For example:</p> +<div class="highlight-python"><pre>%Module qt 5</pre> +</div> +<dl class="directive"> +<dt id="directive-%ModuleCode"> +<tt class="descname">%ModuleCode</tt><a class="headerlink" href="#directive-%ModuleCode" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%ModuleCode + <em>code</em> +%End +</pre> +<p>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.</p> +<p>For example:</p> +<div class="highlight-python"><pre>%ModuleCode +// Print an object on stderr for debugging purposes. +void dump_object(PyObject *o) +{ + PyObject_Print(o, stderr, 0); + fprintf(stderr, "\n"); +} +%End</pre> +</div> +<p>See also <a class="reference internal" href="#directive-%ExportedHeaderCode"><tt class="xref docutils literal"><span class="pre">%ExportedHeaderCode</span></tt></a> and <a class="reference internal" href="#directive-%ModuleHeaderCode"><tt class="xref docutils literal"><span class="pre">%ModuleHeaderCode</span></tt></a>.</p> +<dl class="directive"> +<dt id="directive-%ModuleHeaderCode"> +<tt class="descname">%ModuleHeaderCode</tt><a class="headerlink" href="#directive-%ModuleHeaderCode" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%ModuleHeaderCode + <em>code</em> +%End +</pre> +<p>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.</p> +<p>For example:</p> +<div class="highlight-python"><pre>%ModuleHeaderCode +void dump_object(PyObject *o); +%End</pre> +</div> +<p>See also <a class="reference internal" href="#directive-%ExportedHeaderCode"><tt class="xref docutils literal"><span class="pre">%ExportedHeaderCode</span></tt></a> and <a class="reference internal" href="#directive-%ModuleCode"><tt class="xref docutils literal"><span class="pre">%ModuleCode</span></tt></a>.</p> +<dl class="directive"> +<dt id="directive-%OptionalInclude"> +<tt class="descname">%OptionalInclude</tt><a class="headerlink" href="#directive-%OptionalInclude" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%OptionalInclude <em>filename</em> +</pre> +<p>This directive is identical to the <a class="reference internal" href="#directive-%Include"><tt class="xref docutils literal"><span class="pre">%Include</span></tt></a> directive except that +SIP silently continues processing if <em>filename</em> could not be opened.</p> +<p>For example:</p> +<div class="highlight-python"><pre>%OptionalInclude license.sip</pre> +</div> +<dl class="directive"> +<dt id="directive-%PickleCode"> +<tt class="descname">%PickleCode</tt><a class="headerlink" href="#directive-%PickleCode" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%PickleCode + <em>code</em> +%End +</pre> +<p>This directive is used to specify handwritten code to pickle a C structure or +C++ class instance.</p> +<p>The following variables are made available to the handwritten code:</p> +<dl class="docutils"> +<dt><em>type</em> *sipCpp</dt> +<dd>This is a pointer to the structure or class instance. Its <em>type</em> is a +pointer to the structure or class.</dd> +<dt>PyObject *sipRes</dt> +<dd>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 <tt class="docutils literal"><span class="pre">NULL</span></tt>.</dd> +</dl> +<p>For example:</p> +<div class="highlight-python"><pre>class Point +{ + Point(int x, y); + + int x() const; + int y() const; + +%PickleCode + sipRes = Py_BuildValue("ii", sipCpp->x(), sipCpp->y()); +%End +}</pre> +</div> +<p>Note that SIP works around the Python limitation that prevents nested types +being pickled.</p> +<p>Both named and unnamed enums can be pickled automatically without providing any +handwritten code.</p> +<dl class="directive"> +<dt id="directive-%Platforms"> +<tt class="descname">%Platforms</tt><a class="headerlink" href="#directive-%Platforms" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%Platforms {<em>name</em> <em>name</em> ...} +</pre> +<p>This directive is used to declare a set of platforms. Platforms (along with +<a class="reference internal" href="#directive-%Feature"><tt class="xref docutils literal"><span class="pre">%Feature</span></tt></a> and <a class="reference internal" href="#directive-%Timeline"><tt class="xref docutils literal"><span class="pre">%Timeline</span></tt></a>) are used by the +<a class="reference internal" href="#directive-%If"><tt class="xref docutils literal"><span class="pre">%If</span></tt></a> directive to control whether or not parts of a specification +are processed or ignored.</p> +<p>Platforms are mutually exclusive - only one platform can be enabled at a time. +By default all platforms are disabled. The SIP <tt class="docutils literal"><span class="pre">-t</span></tt> command line option is +used to enable a platform.</p> +<p>For example:</p> +<div class="highlight-python"><pre>%Platforms {WIN32_PLATFORM POSIX_PLATFORM MACOS_PLATFORM} + +%If (WIN32_PLATFORM) +void undocumented(); +%End + +%If (POSIX_PLATFORM) +void documented(); +%End</pre> +</div> +<dl class="directive"> +<dt id="directive-%PostInitialisationCode"> +<tt class="descname">%PostInitialisationCode</tt><a class="headerlink" href="#directive-%PostInitialisationCode" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%PostInitialisationCode + <em>code</em> +%End +</pre> +<p>This directive is used to specify handwritten code that is embedded in-line +at the very end of the generated module initialisation code.</p> +<p>The following variables are made available to the handwritten code:</p> +<dl class="docutils"> +<dt>PyObject *sipModule</dt> +<dd>This is the module object returned by <tt class="docutils literal"><span class="pre">Py_InitModule()</span></tt>.</dd> +<dt>PyObject *sipModuleDict</dt> +<dd>This is the module’s dictionary object returned by <tt class="docutils literal"><span class="pre">Py_ModuleGetDict()</span></tt>.</dd> +</dl> +<p>For example:</p> +<div class="highlight-python"><pre>%PostInitialisationCode + // The code will be executed when the module is first imported and + // after all other initialisation has been completed. +%End</pre> +</div> +<dl class="directive"> +<dt id="directive-%PreInitialisationCode"> +<tt class="descname">%PreInitialisationCode</tt><a class="headerlink" href="#directive-%PreInitialisationCode" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%PreInitialisationCode + <em>code</em> +%End +</pre> +<p>This directive is used to specify handwritten code that is embedded in-line +at the very start of the generated module initialisation code.</p> +<p>For example:</p> +<div class="highlight-python"><pre>%PreInitialisationCode + // The code will be executed when the module is first imported and + // before other initialisation has been completed. +%End</pre> +</div> +<dl class="directive"> +<dt id="directive-%RaiseCode"> +<tt class="descname">%RaiseCode</tt><a class="headerlink" href="#directive-%RaiseCode" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%RaiseCode + <em>code</em> +%End +</pre> +<p>This directive is used as part of the definition of an exception using the +<a class="reference internal" href="#directive-%Exception"><tt class="xref docutils literal"><span class="pre">%Exception</span></tt></a> 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++ <tt class="docutils literal"><span class="pre">catch</span> <span class="pre">()</span></tt> clause.</p> +<p>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:</p> +<div class="highlight-python"><div class="highlight"><pre><span class="n">SIP_BLOCK_THREADS</span> +<span class="n">PyErr_SetNone</span><span class="p">(</span><span class="n">PyErr_Exception</span><span class="p">);</span> +<span class="n">SIP_UNBLOCK_THREADS</span> +</pre></div> +</div> +<p>Finally, the specified code must not include any <tt class="docutils literal"><span class="pre">return</span></tt> statements.</p> +<p>The following variable is made available to the handwritten code:</p> +<dl class="docutils"> +<dt><em>type</em> &sipExceptionRef</dt> +<dd>This is a reference to the caught C++ exception. The <em>type</em> of the +reference is the same as the type defined in the <tt class="docutils literal"><span class="pre">throw</span> <span class="pre">()</span></tt> specifier.</dd> +</dl> +<p>See the <a class="reference internal" href="#directive-%Exception"><tt class="xref docutils literal"><span class="pre">%Exception</span></tt></a> directive for an example.</p> +<dl class="directive"> +<dt id="directive-%SetCode"> +<tt class="descname">%SetCode</tt><a class="headerlink" href="#directive-%SetCode" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%SetCode + <em>code</em> +%End +</pre> +<p>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.</p> +<p>The following variables are made available to the handwritten code:</p> +<dl class="docutils"> +<dt><em>type</em> *sipCpp</dt> +<dd>This is a pointer to the structure or class instance. Its <em>type</em> is a +pointer to the structure or class. It is not made available if the +variable being wrapped is a static class variable.</dd> +<dt>int sipErr</dt> +<dd>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.</dd> +<dt>PyObject *sipPy</dt> +<dd>This is the Python object that the handwritten code should convert.</dd> +<dt>PyObject *sipPyType</dt> +<dd>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 +(<em>not</em> the class in which it is defined). It may be safely cast to a +PyTypeObject * or a sipWrapperType *.</dd> +</dl> +<p>See the <a class="reference internal" href="#directive-%GetCode"><tt class="xref docutils literal"><span class="pre">%GetCode</span></tt></a> directive for an example.</p> +<dl class="directive"> +<dt id="directive-%Timeline"> +<tt class="descname">%Timeline</tt><a class="headerlink" href="#directive-%Timeline" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%Timeline {<em>name</em> <em>name</em> ...} +</pre> +<p>This directive is used to declare a set of versions released over a period of +time. Versions (along with <a class="reference internal" href="#directive-%Feature"><tt class="xref docutils literal"><span class="pre">%Feature</span></tt></a> and <a class="reference internal" href="#directive-%Platforms"><tt class="xref docutils literal"><span class="pre">%Platforms</span></tt></a>) +are used by the <a class="reference internal" href="#directive-%If"><tt class="xref docutils literal"><span class="pre">%If</span></tt></a> directive to control whether or not parts of a +specification are processed or ignored.</p> +<p>Versions are mutually exclusive - only one version can be enabled at a time. +By default all versions are disabled. The SIP <tt class="docutils literal"><span class="pre">-t</span></tt> command line option is +used to enable a version.</p> +<p>For example:</p> +<div class="highlight-python"><pre>%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</pre> +</div> +<p><a class="reference internal" href="#directive-%Timeline"><tt class="xref docutils literal"><span class="pre">%Timeline</span></tt></a> can be used any number of times in a module to allow +multiple libraries to be wrapped in the same module.</p> +<dl class="directive"> +<dt id="directive-%TypeCode"> +<tt class="descname">%TypeCode</tt><a class="headerlink" href="#directive-%TypeCode" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%TypeCode + <em>code</em> +%End +</pre> +<p>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.</p> +<p>For example:</p> +<div class="highlight-python"><pre>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. + +};</pre> +</div> +<p>Because the scope of the code is normally within the generated file that +implements the type, any utility functions would normally be declared +<tt class="docutils literal"><span class="pre">static</span></tt>. However a naming convention should still be adopted to prevent +clashes of function names within a module in case the SIP <tt class="docutils literal"><span class="pre">-j</span></tt> command line +option is used.</p> +<dl class="directive"> +<dt id="directive-%TypeHeaderCode"> +<tt class="descname">%TypeHeaderCode</tt><a class="headerlink" href="#directive-%TypeHeaderCode" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%TypeHeaderCode + <em>code</em> +%End +</pre> +<p>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 <a class="reference internal" href="#directive-%MappedType"><tt class="xref docutils literal"><span class="pre">%MappedType</span></tt></a> directive.</p> +<p>Normally <em>code</em> will be a pre-processor <tt class="docutils literal"><span class="pre">#include</span></tt> statement.</p> +<p>For example:</p> +<div class="highlight-python"><pre>// Wrap the Klass class. +class Klass +{ +%TypeHeaderCode +#include <klass.h> +%End + + // The rest of the class specification. +};</pre> +</div> +<dl class="directive"> +<dt id="directive-%UnitCode"> +<tt class="descname">%UnitCode</tt><a class="headerlink" href="#directive-%UnitCode" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%UnitCode + <em>code</em> +%End +</pre> +<p>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 <tt class="docutils literal"><span class="pre">#include</span></tt> a C++ precompiled header file.</p> +<dl class="directive"> +<dt id="directive-%VirtualCatcherCode"> +<tt class="descname">%VirtualCatcherCode</tt><a class="headerlink" href="#directive-%VirtualCatcherCode" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<pre class="literal-block"> +%VirtualCatcherCode + <em>code</em> +%End +</pre> +<p>For most classes there are corresponding <a class="reference external" href="c_api.html#ref-derived-classes"><em>generated derived classes</em></a> 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.</p> +<p>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.</p> +<p>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.</p> +<p>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.</p> +<p>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:</p> +<div class="highlight-python"><div class="highlight"><pre><span class="n">SIP_BLOCK_THREADS</span> +<span class="n">Py_DECREF</span><span class="p">(</span><span class="n">obj</span><span class="p">);</span> +<span class="n">SIP_UNBLOCK_THREADS</span> +</pre></div> +</div> +<p>The following variables are made available to the handwritten code in the +context of a method:</p> +<dl class="docutils"> +<dt><em>type</em> a0</dt> +<dd>There is a variable for each argument of the C++ signature named <tt class="docutils literal"><span class="pre">a0</span></tt>, +<tt class="docutils literal"><span class="pre">a1</span></tt>, etc. The <em>type</em> of the variable is the same as the type defined in +the specification.</dd> +<dt>int a0Key</dt> +<dd>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 <tt class="docutils literal"><span class="pre">'\0'</span></tt> terminated strings. The variable would normally be passed +to <a title="sipParseResult" class="reference external" href="c_api.html#sipParseResult"><tt class="xref docutils literal"><span class="pre">sipParseResult()</span></tt></a> using either the <tt class="docutils literal"><span class="pre">A</span></tt> or <tt class="docutils literal"><span class="pre">B</span></tt> format +characters.</dd> +<dt>int sipIsErr</dt> +<dd>The handwritten code should set this to a non-zero value, and raise an +appropriate Python exception, if an error is detected.</dd> +<dt>PyObject *sipMethod</dt> +<dd>This object is the Python reimplementation of the virtual C++ method. It +is normally passed to <a title="sipCallMethod" class="reference external" href="c_api.html#sipCallMethod"><tt class="xref docutils literal"><span class="pre">sipCallMethod()</span></tt></a>.</dd> +<dt><em>type</em> sipRes</dt> +<dd>The handwritten code should set this to the result to be returned. The +<em>type</em> of the variable is the same as the type defined in the C++ signature +in the specification.</dd> +<dt>int sipResKey</dt> +<dd>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 <tt class="docutils literal"><span class="pre">'\0'</span></tt> terminated strings. The +variable would normally be passed to <a title="sipParseResult" class="reference external" href="c_api.html#sipParseResult"><tt class="xref docutils literal"><span class="pre">sipParseResult()</span></tt></a> using either +the <tt class="docutils literal"><span class="pre">A</span></tt> or <tt class="docutils literal"><span class="pre">B</span></tt> format characters.</dd> +<dt>sipSimpleWrapper *sipPySelf</dt> +<dd>This variable is only made available if either the <tt class="docutils literal"><span class="pre">a0Key</span></tt> or +<tt class="docutils literal"><span class="pre">sipResKey</span></tt> are made available. It defines the context within which keys +are unique. The variable would normally be passed to +<a title="sipParseResult" class="reference external" href="c_api.html#sipParseResult"><tt class="xref docutils literal"><span class="pre">sipParseResult()</span></tt></a> using the <tt class="docutils literal"><span class="pre">S</span></tt> format character.</dd> +</dl> +<p>No variables are made available in the context of a destructor.</p> +<p>For example:</p> +<div class="highlight-python"><pre>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 +};</pre> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h4>Previous topic</h4> + <p class="topless"><a href="specification_files.html" + title="previous chapter">SIP Specification Files</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="annotations.html" + title="next chapter">Annotations</a></p> + <div id="searchbox" style="display: none"> + <h3>Quick search</h3> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" size="18" /> + <input type="submit" value="Go" /> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </form> + <p class="searchtip" style="font-size: 90%"> + Enter search terms or a module, class or function name. + </p> + </div> + <script type="text/javascript">$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="modindex.html" title="Global Module Index" + >modules</a> |</li> + <li class="right" > + <a href="annotations.html" title="Annotations" + >next</a> |</li> + <li class="right" > + <a href="specification_files.html" title="SIP Specification Files" + >previous</a> |</li> + <li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2010 Riverbank Computing Limited. + Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.4. + </div> + </body> +</html>
\ No newline at end of file diff --git a/doc/html/distutils.html b/doc/html/distutils.html new file mode 100644 index 0000000..9531ffd --- /dev/null +++ b/doc/html/distutils.html @@ -0,0 +1,141 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + + <title>Building Your Extension with distutils — SIP 4.10.5 Reference Guide</title> + <link rel="stylesheet" href="_static/default.css" type="text/css" /> + <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '#', + VERSION: '4.10.5', + COLLAPSE_MODINDEX: false, + FILE_SUFFIX: '.html', + HAS_SOURCE: true + }; + </script> + <script type="text/javascript" src="_static/jquery.js"></script> + <script type="text/javascript" src="_static/doctools.js"></script> + <link rel="top" title="SIP 4.10.5 Reference Guide" href="index.html" /> + <link rel="next" title="Builtin Modules and Custom Interpreters" href="builtin.html" /> + <link rel="prev" title="The Build System" href="build_system.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="modindex.html" title="Global Module Index" + accesskey="M">modules</a> |</li> + <li class="right" > + <a href="builtin.html" title="Builtin Modules and Custom Interpreters" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="build_system.html" title="The Build System" + accesskey="P">previous</a> |</li> + <li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="building-your-extension-with-distutils"> +<span id="ref-distutils"></span><h1>Building Your Extension with distutils<a class="headerlink" href="#building-your-extension-with-distutils" title="Permalink to this headline">¶</a></h1> +<p>To build the example in <a class="reference external" href="using.html#ref-simple-c-example"><em>A Simple C++ Example</em></a> using distutils, it is +sufficient to create a standard <tt class="docutils literal"><span class="pre">setup.py</span></tt>, listing <tt class="docutils literal"><span class="pre">word.sip</span></tt> among the +files to build, and hook-up SIP into distutils:</p> +<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="kn">import</span> <span class="n">setup</span><span class="p">,</span> <span class="n">Extension</span> +<span class="kn">import</span> <span class="nn">sipdistutils</span> + +<span class="n">setup</span><span class="p">(</span> + <span class="n">name</span> <span class="o">=</span> <span class="s">'word'</span><span class="p">,</span> + <span class="n">versione</span> <span class="o">=</span> <span class="s">'1.0'</span><span class="p">,</span> + <span class="n">ext_modules</span><span class="o">=</span><span class="p">[</span> + <span class="n">Extension</span><span class="p">(</span><span class="s">"word"</span><span class="p">,</span> <span class="p">[</span><span class="s">"word.sip"</span><span class="p">,</span> <span class="s">"word.cpp"</span><span class="p">]),</span> + <span class="p">],</span> + + <span class="n">cmdclass</span> <span class="o">=</span> <span class="p">{</span><span class="s">'build_ext'</span><span class="p">:</span> <span class="n">sipdistutils</span><span class="o">.</span><span class="n">build_ext</span><span class="p">}</span> +<span class="p">)</span> +</pre></div> +</div> +<p>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 <tt class="docutils literal"><span class="pre">word.sip</span></tt>. +Then, running <tt class="docutils literal"><span class="pre">setup.py</span> <span class="pre">build</span></tt> will build our extension module.</p> +<p>If you want to use any of sip’s command-line options described in +<a class="reference external" href="command_line.html#ref-command-line"><em>The SIP Command Line</em></a>, there is a new option available for the +<tt class="docutils literal"><span class="pre">build_ext</span></tt> command in distutils: <tt class="docutils literal"><span class="pre">--sip-opts</span></tt>. So you can either invoke +distutils as follows:</p> +<div class="highlight-python"><pre>$ python setup.py build_ext --sip-opts="-e -g" build</pre> +</div> +<p>or you can leverage distutils’ config file support by creating a <tt class="docutils literal"><span class="pre">setup.cfg</span></tt> +file in the supported system or local paths (eg: in the same directory of +<tt class="docutils literal"><span class="pre">setup.py</span></tt>) with these contents:</p> +<div class="highlight-python"><div class="highlight"><pre><span class="p">[</span><span class="n">build_ext</span><span class="p">]</span> +<span class="n">sip</span><span class="o">-</span><span class="n">opts</span> <span class="o">=</span> <span class="o">-</span><span class="n">e</span> <span class="o">-</span><span class="n">g</span> +</pre></div> +</div> +<p>and then run <tt class="docutils literal"><span class="pre">setup.py</span> <span class="pre">build</span></tt> as usual.</p> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h4>Previous topic</h4> + <p class="topless"><a href="build_system.html" + title="previous chapter">The Build System</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="builtin.html" + title="next chapter">Builtin Modules and Custom Interpreters</a></p> + <div id="searchbox" style="display: none"> + <h3>Quick search</h3> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" size="18" /> + <input type="submit" value="Go" /> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </form> + <p class="searchtip" style="font-size: 90%"> + Enter search terms or a module, class or function name. + </p> + </div> + <script type="text/javascript">$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="modindex.html" title="Global Module Index" + >modules</a> |</li> + <li class="right" > + <a href="builtin.html" title="Builtin Modules and Custom Interpreters" + >next</a> |</li> + <li class="right" > + <a href="build_system.html" title="The Build System" + >previous</a> |</li> + <li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2010 Riverbank Computing Limited. + Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.4. + </div> + </body> +</html>
\ No newline at end of file diff --git a/doc/html/embedding.html b/doc/html/embedding.html new file mode 100644 index 0000000..1a61175 --- /dev/null +++ b/doc/html/embedding.html @@ -0,0 +1,162 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + + <title>Using the C API when Embedding — SIP 4.10.5 Reference Guide</title> + <link rel="stylesheet" href="_static/default.css" type="text/css" /> + <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '#', + VERSION: '4.10.5', + COLLAPSE_MODINDEX: false, + FILE_SUFFIX: '.html', + HAS_SOURCE: true + }; + </script> + <script type="text/javascript" src="_static/jquery.js"></script> + <script type="text/javascript" src="_static/doctools.js"></script> + <link rel="top" title="SIP 4.10.5 Reference Guide" href="index.html" /> + <link rel="next" title="Python API for Applications" href="python_api.html" /> + <link rel="prev" title="C API for Handwritten Code" href="c_api.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="modindex.html" title="Global Module Index" + accesskey="M">modules</a> |</li> + <li class="right" > + <a href="python_api.html" title="Python API for Applications" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="c_api.html" title="C API for Handwritten Code" + accesskey="P">previous</a> |</li> + <li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="using-the-c-api-when-embedding"> +<h1>Using the C API when Embedding<a class="headerlink" href="#using-the-c-api-when-embedding" title="Permalink to this headline">¶</a></h1> +<p>The <a class="reference external" href="c_api.html#ref-c-api"><em>C API</em></a> 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.</p> +<p>The API is exported by the SIP module as a <tt class="docutils literal"><span class="pre">sipAPIDef</span></tt> data structure +containing a set of function pointers. The data structure is defined in the +SIP header file <tt class="docutils literal"><span class="pre">sip.h</span></tt>. The data structure is wrapped as a Python +<tt class="docutils literal"><span class="pre">PyCObject</span></tt> object and is referenced by the name <tt class="docutils literal"><span class="pre">_C_API</span></tt> in the SIP +module dictionary.</p> +<p>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 <tt class="docutils literal"><span class="pre">sip</span></tt> prefix with <tt class="docutils literal"><span class="pre">api</span></tt> and converting each word in the +name to lower case and preceding it with an underscore. For example:</p> +<blockquote> +<p><tt class="docutils literal"><span class="pre">sipExportSymbol</span></tt> becomes <tt class="docutils literal"><span class="pre">api_export_symbol</span></tt></p> +<p><tt class="docutils literal"><span class="pre">sipWrapperCheck</span></tt> becomes <tt class="docutils literal"><span class="pre">api_wrapper_check</span></tt></p> +</blockquote> +<p>Note that the type objects that SIP generates for a wrapped module (see +<a class="reference external" href="c_api.html#ref-type-structures"><em>Generated Type Structures</em></a>, <a class="reference external" href="c_api.html#ref-enum-type-objects"><em>Generated Named Enum Type Objects</em></a> and +<a class="reference external" href="c_api.html#ref-exception-objects"><em>Generated Exception Objects</em></a>) cannot be refered to directly and must be +obtained using the <a title="sipFindType" class="reference external" href="c_api.html#sipFindType"><tt class="xref docutils literal"><span class="pre">sipFindType()</span></tt></a> function. Of course, the +corresponding modules must already have been imported into the interpreter.</p> +<p>The following code fragment shows how to get a pointer to the <tt class="docutils literal"><span class="pre">sipAPIDef</span></tt> +data structure:</p> +<div class="highlight-python"><pre>#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); +}</pre> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h4>Previous topic</h4> + <p class="topless"><a href="c_api.html" + title="previous chapter">C API for Handwritten Code</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="python_api.html" + title="next chapter">Python API for Applications</a></p> + <div id="searchbox" style="display: none"> + <h3>Quick search</h3> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" size="18" /> + <input type="submit" value="Go" /> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </form> + <p class="searchtip" style="font-size: 90%"> + Enter search terms or a module, class or function name. + </p> + </div> + <script type="text/javascript">$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="modindex.html" title="Global Module Index" + >modules</a> |</li> + <li class="right" > + <a href="python_api.html" title="Python API for Applications" + >next</a> |</li> + <li class="right" > + <a href="c_api.html" title="C API for Handwritten Code" + >previous</a> |</li> + <li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2010 Riverbank Computing Limited. + Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.4. + </div> + </body> +</html>
\ No newline at end of file diff --git a/doc/html/genindex.html b/doc/html/genindex.html new file mode 100644 index 0000000..8b714a6 --- /dev/null +++ b/doc/html/genindex.html @@ -0,0 +1,784 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + + <title>Index — SIP 4.10.5 Reference Guide</title> + <link rel="stylesheet" href="_static/default.css" type="text/css" /> + <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '#', + VERSION: '4.10.5', + COLLAPSE_MODINDEX: false, + FILE_SUFFIX: '.html', + HAS_SOURCE: true + }; + </script> + <script type="text/javascript" src="_static/jquery.js"></script> + <script type="text/javascript" src="_static/doctools.js"></script> + <link rel="top" title="SIP 4.10.5 Reference Guide" href="index.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="#" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="modindex.html" title="Global Module Index" + accesskey="M">modules</a> |</li> + <li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + + <h1 id="index">Index</h1> + + <a href="#Symbols"><strong>Symbols</strong></a> | <a href="#_"><strong>_</strong></a> | <a href="#A"><strong>A</strong></a> | <a href="#B"><strong>B</strong></a> | <a href="#C"><strong>C</strong></a> | <a href="#D"><strong>D</strong></a> | <a href="#E"><strong>E</strong></a> | <a href="#F"><strong>F</strong></a> | <a href="#G"><strong>G</strong></a> | <a href="#H"><strong>H</strong></a> | <a href="#I"><strong>I</strong></a> | <a href="#K"><strong>K</strong></a> | <a href="#L"><strong>L</strong></a> | <a href="#M"><strong>M</strong></a> | <a href="#N"><strong>N</strong></a> | <a href="#O"><strong>O</strong></a> | <a href="#P"><strong>P</strong></a> | <a href="#R"><strong>R</strong></a> | <a href="#S"><strong>S</strong></a> | <a href="#T"><strong>T</strong></a> | <a href="#U"><strong>U</strong></a> | <a href="#V"><strong>V</strong></a> | <a href="#W"><strong>W</strong></a> + + <hr /> + + +<h2 id="Symbols">Symbols</h2> +<table width="100%" class="indextable"><tr><td width="33%" valign="top"> +<dl> + +<dt><a href="directives.html#directive-%AccessCode">%AccessCode (directive)</a></dt> +<dt><a href="directives.html#directive-%API">%API (directive)</a></dt> +<dt><a href="directives.html#directive-%BIGetBufferCode">%BIGetBufferCode (directive)</a></dt> +<dt><a href="directives.html#directive-%BIGetCharBufferCode">%BIGetCharBufferCode (directive)</a></dt> +<dt><a href="directives.html#directive-%BIGetReadBufferCode">%BIGetReadBufferCode (directive)</a></dt> +<dt><a href="directives.html#directive-%BIGetSegCountCode">%BIGetSegCountCode (directive)</a></dt> +<dt><a href="directives.html#directive-%BIGetWriteBufferCode">%BIGetWriteBufferCode (directive)</a></dt> +<dt><a href="directives.html#directive-%BIReleaseBufferCode">%BIReleaseBufferCode (directive)</a></dt> +<dt><a href="directives.html#directive-%CModule">%CModule (directive)</a></dt> +<dt><a href="directives.html#directive-%CompositeModule">%CompositeModule (directive)</a></dt> +<dt><a href="directives.html#directive-%ConsolidatedModule">%ConsolidatedModule (directive)</a></dt> +<dt><a href="directives.html#directive-%ConvertFromTypeCode">%ConvertFromTypeCode (directive)</a></dt> +<dt><a href="directives.html#directive-%ConvertToSubClassCode">%ConvertToSubClassCode (directive)</a></dt> +<dt><a href="directives.html#directive-%ConvertToTypeCode">%ConvertToTypeCode (directive)</a></dt> +<dt><a href="directives.html#directive-%Copying">%Copying (directive)</a></dt> +<dt><a href="directives.html#directive-%DefaultEncoding">%DefaultEncoding (directive)</a></dt> +<dt><a href="directives.html#directive-%DefaultMetatype">%DefaultMetatype (directive)</a></dt> +<dt><a href="directives.html#directive-%DefaultSupertype">%DefaultSupertype (directive)</a></dt> +<dt><a href="directives.html#directive-%Doc">%Doc (directive)</a></dt> +<dt><a href="directives.html#directive-%Docstring">%Docstring (directive)</a></dt> +<dt><a href="directives.html#directive-%End">%End (directive)</a></dt> +<dt><a href="directives.html#directive-%Exception">%Exception (directive)</a></dt> +<dt><a href="directives.html#directive-%ExportedDoc">%ExportedDoc (directive)</a></dt> +<dt><a href="directives.html#directive-%ExportedHeaderCode">%ExportedHeaderCode (directive)</a></dt> +<dt><a href="directives.html#directive-%Feature">%Feature (directive)</a></dt> +<dt><a href="directives.html#directive-%GCClearCode">%GCClearCode (directive)</a></dt> +<dt><a href="directives.html#directive-%GCTraverseCode">%GCTraverseCode (directive)</a></dt> +<dt><a href="directives.html#directive-%GetCode">%GetCode (directive)</a></dt> +<dt><a href="directives.html#directive-%If">%If (directive)</a></dt> +<dt><a href="directives.html#directive-%Import">%Import (directive)</a></dt> +<dt><a href="directives.html#directive-%Include">%Include (directive)</a></dt> +<dt><a href="directives.html#directive-%InitialisationCode">%InitialisationCode (directive)</a></dt> +<dt><a href="directives.html#directive-%License">%License (directive)</a></dt> +<dt><a href="directives.html#directive-%MappedType">%MappedType (directive)</a></dt> +<dt><a href="directives.html#directive-%MethodCode">%MethodCode (directive)</a></dt> +<dt><a href="directives.html#directive-%Module">%Module (directive)</a></dt> +<dt><a href="directives.html#directive-%ModuleCode">%ModuleCode (directive)</a></dt> +<dt><a href="directives.html#directive-%ModuleHeaderCode">%ModuleHeaderCode (directive)</a></dt> +<dt><a href="directives.html#directive-%OptionalInclude">%OptionalInclude (directive)</a></dt> +<dt><a href="directives.html#directive-%PickleCode">%PickleCode (directive)</a></dt> +<dt><a href="directives.html#directive-%Platforms">%Platforms (directive)</a></dt> +<dt><a href="directives.html#directive-%PostInitialisationCode">%PostInitialisationCode (directive)</a></dt> +<dt><a href="directives.html#directive-%PreInitialisationCode">%PreInitialisationCode (directive)</a></dt> +<dt><a href="directives.html#directive-%RaiseCode">%RaiseCode (directive)</a></dt> +<dt><a href="directives.html#directive-%SetCode">%SetCode (directive)</a></dt> +<dt><a href="directives.html#directive-%Timeline">%Timeline (directive)</a></dt> +<dt><a href="directives.html#directive-%TypeCode">%TypeCode (directive)</a></dt> +<dt><a href="directives.html#directive-%TypeHeaderCode">%TypeHeaderCode (directive)</a></dt> +<dt><a href="directives.html#directive-%UnitCode">%UnitCode (directive)</a></dt> +<dt><a href="directives.html#directive-%VirtualCatcherCode">%VirtualCatcherCode (directive)</a></dt> +<dt>--arch <ARCH></dt> + <dd><dl> + <dt><a href="installation.html#cmdoption-configure.py--arch">configure.py command line option</a></dt> + </dl></dd> +<dt>--show-build-macros</dt> + <dd><dl> + <dt><a href="installation.html#cmdoption-configure.py--show-build-macros">configure.py command line option</a></dt> + </dl></dd> +<dt>--show-platforms</dt> + <dd><dl> + <dt><a href="installation.html#cmdoption-configure.py--show-platforms">configure.py command line option</a></dt> + </dl></dd> +<dt>--version</dt> + <dd><dl> + <dt><a href="installation.html#cmdoption-configure.py--version">configure.py command line option</a></dt> + </dl></dd> +<dt>-a <FILE></dt> + <dd><dl> + <dt><a href="command_line.html#cmdoption-sip-a">sip command line option</a></dt> + </dl></dd></dl></td><td width="33%" valign="top"><dl> +<dt>-b <DIR>, --bindir <DIR></dt> + <dd><dl> + <dt><a href="installation.html#cmdoption-configure.py-b">configure.py command line option</a></dt> + </dl></dd> +<dt>-b <FILE></dt> + <dd><dl> + <dt><a href="command_line.html#cmdoption-sip-b">sip command line option</a></dt> + </dl></dd> +<dt>-c <DIR></dt> + <dd><dl> + <dt><a href="command_line.html#cmdoption-sip-c">sip command line option</a></dt> + </dl></dd> +<dt>-d <DIR>, --destdir <DIR></dt> + <dd><dl> + <dt><a href="installation.html#cmdoption-configure.py-d">configure.py command line option</a></dt> + </dl></dd> +<dt>-d <FILE></dt> + <dd><dl> + <dt><a href="command_line.html#cmdoption-sip-d">sip command line option</a></dt> + </dl></dd> +<dt>-e</dt> + <dd><dl> + <dt><a href="command_line.html#cmdoption-sip-e">sip command line option</a></dt> + </dl></dd> +<dt>-e <DIR>, --incdir <DIR></dt> + <dd><dl> + <dt><a href="installation.html#cmdoption-configure.py-e">configure.py command line option</a></dt> + </dl></dd> +<dt>-g</dt> + <dd><dl> + <dt><a href="command_line.html#cmdoption-sip-g">sip command line option</a></dt> + </dl></dd> +<dt>-h</dt> + <dd><dl> + <dt><a href="command_line.html#cmdoption-sip-h">sip command line option</a></dt> + </dl></dd> +<dt>-h, --help</dt> + <dd><dl> + <dt><a href="installation.html#cmdoption-configure.py-h">configure.py command line option</a></dt> + </dl></dd> +<dt>-I <DIR></dt> + <dd><dl> + <dt><a href="command_line.html#cmdoption-sip-I">sip command line option</a></dt> + </dl></dd> +<dt>-j <NUMBER></dt> + <dd><dl> + <dt><a href="command_line.html#cmdoption-sip-j">sip command line option</a></dt> + </dl></dd> +<dt>-k</dt> + <dd><dl> + <dt><a href="command_line.html#cmdoption-sip-k">sip command line option</a></dt> + </dl></dd> +<dt>-k, --static</dt> + <dd><dl> + <dt><a href="installation.html#cmdoption-configure.py-k">configure.py command line option</a></dt> + </dl></dd> +<dt>-n, --universal</dt> + <dd><dl> + <dt><a href="installation.html#cmdoption-configure.py-n">configure.py command line option</a></dt> + </dl></dd> +<dt>-o</dt> + <dd><dl> + <dt><a href="command_line.html#cmdoption-sip-o">sip command line option</a></dt> + </dl></dd> +<dt>-P</dt> + <dd><dl> + <dt><a href="command_line.html#cmdoption-sip-P">sip command line option</a></dt> + </dl></dd> +<dt>-p <MODULE></dt> + <dd><dl> + <dt><a href="command_line.html#cmdoption-sip-p">sip command line option</a></dt> + </dl></dd> +<dt>-p <PLATFORM>, --platform <PLATFORM></dt> + <dd><dl> + <dt><a href="installation.html#cmdoption-configure.py-p">configure.py command line option</a></dt> + </dl></dd> +<dt>-r</dt> + <dd><dl> + <dt><a href="command_line.html#cmdoption-sip-r">sip command line option</a></dt> + </dl></dd> +<dt>-s <SDK>, --sdk <SDK></dt> + <dd><dl> + <dt><a href="installation.html#cmdoption-configure.py-s">configure.py command line option</a></dt> + </dl></dd> +<dt>-s <SUFFIX></dt> + <dd><dl> + <dt><a href="command_line.html#cmdoption-sip-s">sip command line option</a></dt> + </dl></dd> +<dt>-t <TAG></dt> + <dd><dl> + <dt><a href="command_line.html#cmdoption-sip-t">sip command line option</a></dt> + </dl></dd> +<dt>-u, --debug</dt> + <dd><dl> + <dt><a href="installation.html#cmdoption-configure.py-u">configure.py command line option</a></dt> + </dl></dd> +<dt>-V</dt> + <dd><dl> + <dt><a href="command_line.html#cmdoption-sip-V">sip command line option</a></dt> + </dl></dd> +<dt>-v <DIR>, --sipdir <DIR></dt> + <dd><dl> + <dt><a href="installation.html#cmdoption-configure.py-v">configure.py command line option</a></dt> + </dl></dd> +<dt>-w</dt> + <dd><dl> + <dt><a href="command_line.html#cmdoption-sip-w">sip command line option</a></dt> + </dl></dd> +<dt>-x <FEATURE></dt> + <dd><dl> + <dt><a href="command_line.html#cmdoption-sip-x">sip command line option</a></dt> + </dl></dd> +<dt>-z <FILE></dt> + <dd><dl> + <dt><a href="command_line.html#cmdoption-sip-z">sip command line option</a></dt> + </dl></dd> +</dl></td></tr></table> + +<h2 id="_">_</h2> +<table width="100%" class="indextable"><tr><td width="33%" valign="top"> +<dl> + +<dt><a href="python_api.html#sip.voidptr.__hex__">__hex__() (sip.voidptr method)</a></dt> +<dt><a href="python_api.html#sip.voidptr.__init__">__init__() (sip.voidptr method)</a></dt> + <dd><dl> + <dt><a href="build_system.html#sipconfig.Configuration.__init__">(sipconfig.Configuration method)</a></dt> + <dt><a href="build_system.html#sipconfig.Makefile.__init__">(sipconfig.Makefile method)</a></dt> + <dt><a href="build_system.html#sipconfig.ModuleMakefile.__init__">(sipconfig.ModuleMakefile method)</a></dt> + <dt><a href="build_system.html#sipconfig.ParentMakefile.__init__">(sipconfig.ParentMakefile method)</a></dt> + <dt><a href="build_system.html#sipconfig.ProgramMakefile.__init__">(sipconfig.ProgramMakefile method)</a></dt> + <dt><a href="build_system.html#sipconfig.PythonModuleMakefile.__init__">(sipconfig.PythonModuleMakefile method)</a></dt> + <dt><a href="build_system.html#sipconfig.SIPModuleMakefile.__init__">(sipconfig.SIPModuleMakefile method)</a></dt> + </dl></dd></dl></td><td width="33%" valign="top"><dl> +<dt><a href="python_api.html#sip.voidptr.__int__">__int__() (sip.voidptr method)</a></dt> +<dt><a href="annotations.html#fanno-__len__">__len__ (function annotation)</a></dt> +</dl></td></tr></table> + +<h2 id="A">A</h2> +<table width="100%" class="indextable"><tr><td width="33%" valign="top"> +<dl> + +<dt><a href="annotations.html#canno-Abstract">Abstract (class annotation)</a></dt> +<dt><a href="annotations.html#aanno-AllowNone">AllowNone (argument annotation)</a></dt> + <dd><dl> + <dt><a href="annotations.html#canno-AllowNone">(class annotation)</a></dt> + <dt><a href="annotations.html#manno-AllowNone">(mapped type annotation)</a></dt> + </dl></dd> +<dt><a href="annotations.html#canno-API">API (class annotation)</a></dt> + <dd><dl> + <dt><a href="annotations.html#fanno-API">(function annotation)</a></dt> + <dt><a href="annotations.html#manno-API">(mapped type annotation)</a></dt> + </dl></dd> +<dt><a href="build_system.html#sipconfig.Configuration.arch">arch (sipconfig.Configuration attribute)</a></dt></dl></td><td width="33%" valign="top"><dl> +<dt><a href="annotations.html#aanno-Array">Array (argument annotation)</a></dt> +<dt><a href="annotations.html#aanno-ArraySize">ArraySize (argument annotation)</a></dt> +<dt><a href="python_api.html#sip.voidptr.ascapsule">ascapsule() (sip.voidptr method)</a></dt> +<dt><a href="python_api.html#sip.voidptr.ascobject">ascobject() (sip.voidptr method)</a></dt> +<dt><a href="python_api.html#sip.voidptr.asstring">asstring() (sip.voidptr method)</a></dt> +<dt><a href="annotations.html#fanno-AutoGen">AutoGen (function annotation)</a></dt> +</dl></td></tr></table> + +<h2 id="B">B</h2> +<table width="100%" class="indextable"><tr><td width="33%" valign="top"> +<dl> + +<dt><a href="build_system.html#sipconfig.ProgramMakefile.build_command">build_command() (sipconfig.ProgramMakefile method)</a></dt> +<dt><a href="build_system.html#sipconfig.Configuration.build_macros">build_macros() (sipconfig.Configuration method)</a></dt></dl></td><td width="33%" valign="top"><dl> +</dl></td></tr></table> + +<h2 id="C">C</h2> +<table width="100%" class="indextable"><tr><td width="33%" valign="top"> +<dl> + +<dt><a href="python_api.html#sip.cast">cast() (in module sip)</a></dt> +<dt><a href="build_system.html#sipconfig.Makefile.chkdir">chkdir (sipconfig.Makefile attribute)</a></dt> +<dt><a href="build_system.html#sipconfig.Makefile.clean_build_file_objects">clean_build_file_objects() (sipconfig.Makefile method)</a></dt> +<dt><a href="build_system.html#sipconfig.Makefile.config">config (sipconfig.Makefile attribute)</a></dt> +<dt><a href="build_system.html#sipconfig.Configuration">Configuration (class in sipconfig)</a></dt> +<dt>configure.py command line option</dt> + <dd><dl> + <dt><a href="installation.html#cmdoption-configure.py--arch">--arch <ARCH></a></dt> + <dt><a href="installation.html#cmdoption-configure.py--show-build-macros">--show-build-macros</a></dt> + <dt><a href="installation.html#cmdoption-configure.py--show-platforms">--show-platforms</a></dt> + <dt><a href="installation.html#cmdoption-configure.py--version">--version</a></dt> + <dt><a href="installation.html#cmdoption-configure.py-b">-b <DIR>, --bindir <DIR></a></dt> + <dt><a href="installation.html#cmdoption-configure.py-d">-d <DIR>, --destdir <DIR></a></dt> + <dt><a href="installation.html#cmdoption-configure.py-e">-e <DIR>, --incdir <DIR></a></dt> + <dt><a href="installation.html#cmdoption-configure.py-h">-h, --help</a></dt> + <dt><a href="installation.html#cmdoption-configure.py-k">-k, --static</a></dt> + <dt><a href="installation.html#cmdoption-configure.py-n">-n, --universal</a></dt> + <dt><a href="installation.html#cmdoption-configure.py-p">-p <PLATFORM>, --platform <PLATFORM></a></dt> + <dt><a href="installation.html#cmdoption-configure.py-s">-s <SDK>, --sdk <SDK></a></dt> + <dt><a href="installation.html#cmdoption-configure.py-u">-u, --debug</a></dt> + <dt><a href="installation.html#cmdoption-configure.py-v">-v <DIR>, --sipdir <DIR></a></dt> + </dl></dd></dl></td><td width="33%" valign="top"><dl> +<dt><a href="build_system.html#sipconfig.Makefile.console">console (sipconfig.Makefile attribute)</a></dt> +<dt><a href="annotations.html#aanno-Constrained">Constrained (argument annotation)</a></dt> +<dt><a href="build_system.html#sipconfig.Makefile.copy">copy (sipconfig.Makefile attribute)</a></dt> +<dt><a href="build_system.html#sipconfig.create_config_module">create_config_module() (in module sipconfig)</a></dt> +<dt><a href="build_system.html#sipconfig.create_content">create_content() (in module sipconfig)</a></dt> +<dt><a href="build_system.html#sipconfig.create_wrapper">create_wrapper() (in module sipconfig)</a></dt> +</dl></td></tr></table> + +<h2 id="D">D</h2> +<table width="100%" class="indextable"><tr><td width="33%" valign="top"> +<dl> + +<dt><a href="annotations.html#dd_isderived">dd_isderived (C member)</a></dt> +<dt><a href="annotations.html#dd_name">dd_name (C member)</a></dt> +<dt><a href="annotations.html#dd_next">dd_next (C member)</a></dt> +<dt><a href="annotations.html#dd_ptr">dd_ptr (C member)</a></dt> +<dt><a href="annotations.html#xanno-Default">Default (exception annotation)</a></dt> + <dd><dl> + <dt><a href="annotations.html#fanno-Default">(function annotation)</a></dt> + </dl></dd> +<dt><a href="build_system.html#sipconfig.Configuration.default_bin_dir">default_bin_dir (sipconfig.Configuration attribute)</a></dt> +<dt><a href="build_system.html#sipconfig.Configuration.default_mod_dir">default_mod_dir (sipconfig.Configuration attribute)</a></dt> +<dt><a href="build_system.html#sipconfig.Configuration.default_sip_dir">default_sip_dir (sipconfig.Configuration attribute)</a></dt> +<dt><a href="annotations.html#canno-DelayDtor">DelayDtor (class annotation)</a></dt></dl></td><td width="33%" valign="top"><dl> +<dt><a href="python_api.html#sip.delete">delete() (in module sip)</a></dt> +<dt><a href="annotations.html#canno-Deprecated">Deprecated (class annotation)</a></dt> + <dd><dl> + <dt><a href="annotations.html#fanno-Deprecated">(function annotation)</a></dt> + </dl></dd> +<dt><a href="annotations.html#aanno-DocType">DocType (argument annotation)</a></dt> + <dd><dl> + <dt><a href="annotations.html#fanno-DocType">(function annotation)</a></dt> + <dt><a href="annotations.html#manno-DocType">(mapped type annotation)</a></dt> + <dt><a href="annotations.html#vanno-DocType">(variable annotation)</a></dt> + </dl></dd> +<dt><a href="annotations.html#aanno-DocValue">DocValue (argument annotation)</a></dt> +<dt><a href="python_api.html#sip.dump">dump() (in module sip)</a></dt> +</dl></td></tr></table> + +<h2 id="E">E</h2> +<table width="100%" class="indextable"><tr><td width="33%" valign="top"> +<dl> + +<dt><a href="annotations.html#aanno-Encoding">Encoding (argument annotation)</a></dt> +<dt><a href="build_system.html#sipconfig.error">error() (in module sipconfig)</a></dt> +<dt><a href="annotations.html#canno-External">External (class annotation)</a></dt> +<dt><a href="build_system.html#sipconfig.Makefile.extra_cflags">extra_cflags (sipconfig.Makefile attribute)</a></dt> +<dt><a href="build_system.html#sipconfig.Makefile.extra_cxxflags">extra_cxxflags (sipconfig.Makefile attribute)</a></dt> +<dt><a href="build_system.html#sipconfig.Makefile.extra_defines">extra_defines (sipconfig.Makefile attribute)</a></dt></dl></td><td width="33%" valign="top"><dl> +<dt><a href="build_system.html#sipconfig.Makefile.extra_include_dirs">extra_include_dirs (sipconfig.Makefile attribute)</a></dt> +<dt><a href="build_system.html#sipconfig.Makefile.extra_lflags">extra_lflags (sipconfig.Makefile attribute)</a></dt> +<dt><a href="build_system.html#sipconfig.Makefile.extra_lib_dirs">extra_lib_dirs (sipconfig.Makefile attribute)</a></dt> +<dt><a href="build_system.html#sipconfig.Makefile.extra_libs">extra_libs (sipconfig.Makefile attribute)</a></dt> +</dl></td></tr></table> + +<h2 id="F">F</h2> +<table width="100%" class="indextable"><tr><td width="33%" valign="top"> +<dl> + +<dt><a href="annotations.html#fanno-Factory">Factory (function annotation)</a></dt> +<dt><a href="build_system.html#sipconfig.Makefile.finalise">finalise() (sipconfig.Makefile method)</a></dt> + <dd><dl> + <dt><a href="build_system.html#sipconfig.ModuleMakefile.finalise">(sipconfig.ModuleMakefile method)</a></dt> + <dt><a href="build_system.html#sipconfig.ProgramMakefile.finalise">(sipconfig.ProgramMakefile method)</a></dt> + <dt><a href="build_system.html#sipconfig.SIPModuleMakefile.finalise">(sipconfig.SIPModuleMakefile method)</a></dt> + </dl></dd></dl></td><td width="33%" valign="top"><dl> +<dt><a href="build_system.html#sipconfig.format">format() (in module sipconfig)</a></dt> +</dl></td></tr></table> + +<h2 id="G">G</h2> +<table width="100%" class="indextable"><tr><td width="33%" valign="top"> +<dl> + +<dt><a href="build_system.html#sipconfig.Makefile.generate">generate() (sipconfig.Makefile method)</a></dt> +<dt><a href="build_system.html#sipconfig.Makefile.generate_macros_and_rules">generate_macros_and_rules() (sipconfig.Makefile method)</a></dt> + <dd><dl> + <dt><a href="build_system.html#sipconfig.ModuleMakefile.generate_macros_and_rules">(sipconfig.ModuleMakefile method)</a></dt> + <dt><a href="build_system.html#sipconfig.ParentMakefile.generate_macros_and_rules">(sipconfig.ParentMakefile method)</a></dt> + <dt><a href="build_system.html#sipconfig.ProgramMakefile.generate_macros_and_rules">(sipconfig.ProgramMakefile method)</a></dt> + <dt><a href="build_system.html#sipconfig.PythonModuleMakefile.generate_macros_and_rules">(sipconfig.PythonModuleMakefile method)</a></dt> + </dl></dd> +<dt><a href="build_system.html#sipconfig.Makefile.generate_target_clean">generate_target_clean() (sipconfig.Makefile method)</a></dt> + <dd><dl> + <dt><a href="build_system.html#sipconfig.ModuleMakefile.generate_target_clean">(sipconfig.ModuleMakefile method)</a></dt> + <dt><a href="build_system.html#sipconfig.ParentMakefile.generate_target_clean">(sipconfig.ParentMakefile method)</a></dt> + <dt><a href="build_system.html#sipconfig.ProgramMakefile.generate_target_clean">(sipconfig.ProgramMakefile method)</a></dt> + </dl></dd> +<dt><a href="build_system.html#sipconfig.Makefile.generate_target_default">generate_target_default() (sipconfig.Makefile method)</a></dt> + <dd><dl> + <dt><a href="build_system.html#sipconfig.ModuleMakefile.generate_target_default">(sipconfig.ModuleMakefile method)</a></dt> + <dt><a href="build_system.html#sipconfig.ParentMakefile.generate_target_default">(sipconfig.ParentMakefile method)</a></dt> + <dt><a href="build_system.html#sipconfig.ProgramMakefile.generate_target_default">(sipconfig.ProgramMakefile method)</a></dt> + </dl></dd></dl></td><td width="33%" valign="top"><dl> +<dt><a href="build_system.html#sipconfig.Makefile.generate_target_install">generate_target_install() (sipconfig.Makefile method)</a></dt> + <dd><dl> + <dt><a href="build_system.html#sipconfig.ModuleMakefile.generate_target_install">(sipconfig.ModuleMakefile method)</a></dt> + <dt><a href="build_system.html#sipconfig.ParentMakefile.generate_target_install">(sipconfig.ParentMakefile method)</a></dt> + <dt><a href="build_system.html#sipconfig.ProgramMakefile.generate_target_install">(sipconfig.ProgramMakefile method)</a></dt> + <dt><a href="build_system.html#sipconfig.PythonModuleMakefile.generate_target_install">(sipconfig.PythonModuleMakefile method)</a></dt> + </dl></dd> +<dt><a href="build_system.html#sipconfig.Makefile.generator">generator (sipconfig.Makefile attribute)</a></dt> +<dt><a href="python_api.html#sip.getapi">getapi() (in module sip)</a></dt> +<dt><a href="python_api.html#sip.voidptr.getsize">getsize() (sip.voidptr method)</a></dt> +<dt><a href="annotations.html#aanno-GetWrapper">GetWrapper (argument annotation)</a></dt> +<dt><a href="python_api.html#sip.voidptr.getwriteable">getwriteable() (sip.voidptr method)</a></dt> +</dl></td></tr></table> + +<h2 id="H">H</h2> +<table width="100%" class="indextable"><tr><td width="33%" valign="top"> +<dl> + +<dt><a href="annotations.html#fanno-HoldGIL">HoldGIL (function annotation)</a></dt></dl></td><td width="33%" valign="top"><dl> +</dl></td></tr></table> + +<h2 id="I">I</h2> +<table width="100%" class="indextable"><tr><td width="33%" valign="top"> +<dl> + +<dt><a href="annotations.html#aanno-In">In (argument annotation)</a></dt> +<dt><a href="build_system.html#sipconfig.inform">inform() (in module sipconfig)</a></dt> +<dt><a href="build_system.html#sipconfig.Makefile.install_file">install_file() (sipconfig.Makefile method)</a></dt></dl></td><td width="33%" valign="top"><dl> +<dt><a href="python_api.html#sip.isdeleted">isdeleted() (in module sip)</a></dt> +<dt><a href="python_api.html#sip.ispyowned">ispyowned() (in module sip)</a></dt> +</dl></td></tr></table> + +<h2 id="K">K</h2> +<table width="100%" class="indextable"><tr><td width="33%" valign="top"> +<dl> + +<dt><a href="annotations.html#aanno-KeepReference">KeepReference (argument annotation)</a></dt> +<dt><a href="annotations.html#fanno-KeywordArgs">KeywordArgs (function annotation)</a></dt></dl></td><td width="33%" valign="top"><dl> +</dl></td></tr></table> + +<h2 id="L">L</h2> +<table width="100%" class="indextable"><tr><td width="33%" valign="top"> +<dl> + +<dt><a href="annotations.html#lanno-Licensee">Licensee (license annotation)</a></dt></dl></td><td width="33%" valign="top"><dl> +</dl></td></tr></table> + +<h2 id="M">M</h2> +<table width="100%" class="indextable"><tr><td width="33%" valign="top"> +<dl> + +<dt><a href="build_system.html#sipconfig.Makefile">Makefile (class in sipconfig)</a></dt> +<dt><a href="annotations.html#canno-Metatype">Metatype (class annotation)</a></dt> +<dt><a href="build_system.html#sipconfig.Makefile.mkdir">mkdir (sipconfig.Makefile attribute)</a></dt></dl></td><td width="33%" valign="top"><dl> +<dt><a href="build_system.html#sipconfig.ModuleMakefile.module_as_lib">module_as_lib() (sipconfig.ModuleMakefile method)</a></dt> +<dt><a href="build_system.html#sipconfig.ModuleMakefile">ModuleMakefile (class in sipconfig)</a></dt> +</dl></td></tr></table> + +<h2 id="N">N</h2> +<table width="100%" class="indextable"><tr><td width="33%" valign="top"> +<dl> + +<dt><a href="annotations.html#fanno-NewThread">NewThread (function annotation)</a></dt> +<dt><a href="annotations.html#fanno-NoArgParser">NoArgParser (function annotation)</a></dt> +<dt><a href="annotations.html#aanno-NoCopy">NoCopy (argument annotation)</a></dt> + <dd><dl> + <dt><a href="annotations.html#fanno-NoCopy">(function annotation)</a></dt> + </dl></dd> +<dt><a href="annotations.html#canno-NoDefaultCtors">NoDefaultCtors (class annotation)</a></dt> +<dt><a href="annotations.html#fanno-NoDerived">NoDerived (function annotation)</a></dt></dl></td><td width="33%" valign="top"><dl> +<dt><a href="annotations.html#fanno-NoKeywordArgs">NoKeywordArgs (function annotation)</a></dt> +<dt><a href="annotations.html#manno-NoRelease">NoRelease (mapped type annotation)</a></dt> +<dt><a href="annotations.html#tanno-NoTypeName">NoTypeName (typedef annotation)</a></dt> +<dt><a href="annotations.html#fanno-Numeric">Numeric (function annotation)</a></dt> +</dl></td></tr></table> + +<h2 id="O">O</h2> +<table width="100%" class="indextable"><tr><td width="33%" valign="top"> +<dl> + +<dt><a href="build_system.html#sipconfig.Makefile.optional_list">optional_list() (sipconfig.Makefile method)</a></dt> +<dt><a href="build_system.html#sipconfig.Makefile.optional_string">optional_string() (sipconfig.Makefile method)</a></dt></dl></td><td width="33%" valign="top"><dl> +<dt><a href="annotations.html#aanno-Out">Out (argument annotation)</a></dt> +</dl></td></tr></table> + +<h2 id="P">P</h2> +<table width="100%" class="indextable"><tr><td width="33%" valign="top"> +<dl> + +<dt><a href="build_system.html#sipconfig.ParentMakefile">ParentMakefile (class in sipconfig)</a></dt> +<dt><a href="build_system.html#sipconfig.Makefile.parse_build_file">parse_build_file() (sipconfig.Makefile method)</a></dt> +<dt><a href="build_system.html#sipconfig.parse_build_macros">parse_build_macros() (in module sipconfig)</a></dt> +<dt><a href="build_system.html#sipconfig.Configuration.platform">platform (sipconfig.Configuration attribute)</a></dt> +<dt><a href="build_system.html#sipconfig.Makefile.platform_lib">platform_lib() (sipconfig.Makefile method)</a></dt> +<dt><a href="annotations.html#fanno-PostHook">PostHook (function annotation)</a></dt> +<dt><a href="annotations.html#fanno-PreHook">PreHook (function annotation)</a></dt> +<dt><a href="build_system.html#sipconfig.ProgramMakefile">ProgramMakefile (class in sipconfig)</a></dt> +<dt><a href="build_system.html#sipconfig.Configuration.py_conf_inc_dir">py_conf_inc_dir (sipconfig.Configuration attribute)</a></dt> +<dt><a href="build_system.html#sipconfig.Configuration.py_inc_dir">py_inc_dir (sipconfig.Configuration attribute)</a></dt></dl></td><td width="33%" valign="top"><dl> +<dt><a href="build_system.html#sipconfig.Configuration.py_lib_dir">py_lib_dir (sipconfig.Configuration attribute)</a></dt> +<dt><a href="build_system.html#sipconfig.Configuration.py_version">py_version (sipconfig.Configuration attribute)</a></dt> +<dt><a href="annotations.html#canno-PyName">PyName (class annotation)</a></dt> + <dd><dl> + <dt><a href="annotations.html#eanno-PyName">(enum annotation)</a></dt> + <dt><a href="annotations.html#xanno-PyName">(exception annotation)</a></dt> + <dt><a href="annotations.html#fanno-PyName">(function annotation)</a></dt> + <dt><a href="annotations.html#vanno-PyName">(variable annotation)</a></dt> + </dl></dd> +<dt><a href="build_system.html#sipconfig.PythonModuleMakefile">PythonModuleMakefile (class in sipconfig)</a></dt> +</dl></td></tr></table> + +<h2 id="R">R</h2> +<table width="100%" class="indextable"><tr><td width="33%" valign="top"> +<dl> + +<dt><a href="build_system.html#sipconfig.read_version">read_version() (in module sipconfig)</a></dt> +<dt><a href="build_system.html#sipconfig.Makefile.ready">ready() (sipconfig.Makefile method)</a></dt> +<dt><a href="annotations.html#fanno-ReleaseGIL">ReleaseGIL (function annotation)</a></dt> +<dt><a href="build_system.html#sipconfig.Makefile.required_string">required_string() (sipconfig.Makefile method)</a></dt></dl></td><td width="33%" valign="top"><dl> +<dt><a href="annotations.html#aanno-ResultSize">ResultSize (argument annotation)</a></dt> +<dt><a href="build_system.html#sipconfig.Makefile.rm">rm (sipconfig.Makefile attribute)</a></dt> +</dl></td></tr></table> + +<h2 id="S">S</h2> +<table width="100%" class="indextable"><tr><td width="33%" valign="top"> +<dl> + +<dt><a href="build_system.html#sipconfig.Configuration.set_build_macros">set_build_macros() (sipconfig.Configuration method)</a></dt> +<dt><a href="python_api.html#sip.setapi">setapi() (in module sip)</a></dt> +<dt><a href="python_api.html#sip.setdeleted">setdeleted() (in module sip)</a></dt> +<dt><a href="python_api.html#sip.voidptr.setsize">setsize() (sip.voidptr method)</a></dt> +<dt><a href="python_api.html#sip.settracemask">settracemask() (in module sip)</a></dt> +<dt><a href="python_api.html#sip.voidptr.setwriteable">setwriteable() (sip.voidptr method)</a></dt> +<dt><a href="annotations.html#lanno-Signature">Signature (license annotation)</a></dt> +<dt><a href="annotations.html#aanno-SingleShot">SingleShot (argument annotation)</a></dt> +<dt><a href="python_api.html#module-sip">sip (module)</a></dt> +<dt>sip command line option</dt> + <dd><dl> + <dt><a href="command_line.html#cmdoption-sip-I">-I <DIR></a></dt> + <dt><a href="command_line.html#cmdoption-sip-P">-P</a></dt> + <dt><a href="command_line.html#cmdoption-sip-V">-V</a></dt> + <dt><a href="command_line.html#cmdoption-sip-a">-a <FILE></a></dt> + <dt><a href="command_line.html#cmdoption-sip-b">-b <FILE></a></dt> + <dt><a href="command_line.html#cmdoption-sip-c">-c <DIR></a></dt> + <dt><a href="command_line.html#cmdoption-sip-d">-d <FILE></a></dt> + <dt><a href="command_line.html#cmdoption-sip-e">-e</a></dt> + <dt><a href="command_line.html#cmdoption-sip-g">-g</a></dt> + <dt><a href="command_line.html#cmdoption-sip-h">-h</a></dt> + <dt><a href="command_line.html#cmdoption-sip-j">-j <NUMBER></a></dt> + <dt><a href="command_line.html#cmdoption-sip-k">-k</a></dt> + <dt><a href="command_line.html#cmdoption-sip-o">-o</a></dt> + <dt><a href="command_line.html#cmdoption-sip-p">-p <MODULE></a></dt> + <dt><a href="command_line.html#cmdoption-sip-r">-r</a></dt> + <dt><a href="command_line.html#cmdoption-sip-s">-s <SUFFIX></a></dt> + <dt><a href="command_line.html#cmdoption-sip-t">-t <TAG></a></dt> + <dt><a href="command_line.html#cmdoption-sip-w">-w</a></dt> + <dt><a href="command_line.html#cmdoption-sip-x">-x <FEATURE></a></dt> + <dt><a href="command_line.html#cmdoption-sip-z">-z <FILE></a></dt> + </dl></dd> +<dt><a href="specification_files.html#stype-SIP_ANYSLOT">SIP_ANYSLOT (SIP type)</a></dt> +<dt><a href="c_api.html#SIP_API_MAJOR_NR">SIP_API_MAJOR_NR (C macro)</a></dt> +<dt><a href="c_api.html#SIP_API_MINOR_NR">SIP_API_MINOR_NR (C macro)</a></dt> +<dt><a href="build_system.html#sipconfig.Configuration.sip_bin">sip_bin (sipconfig.Configuration attribute)</a></dt> +<dt><a href="c_api.html#SIP_BLOCK_THREADS">SIP_BLOCK_THREADS (C macro)</a></dt> +<dt><a href="build_system.html#sipconfig.Configuration.sip_config_args">sip_config_args (sipconfig.Configuration attribute)</a></dt> +<dt><a href="build_system.html#sipconfig.Configuration.sip_inc_dir">sip_inc_dir (sipconfig.Configuration attribute)</a></dt> +<dt><a href="build_system.html#sipconfig.Configuration.sip_mod_dir">sip_mod_dir (sipconfig.Configuration attribute)</a></dt> +<dt><a href="c_api.html#SIP_NO_CONVERTORS">SIP_NO_CONVERTORS (C macro)</a></dt> +<dt><a href="c_api.html#SIP_NOT_NONE">SIP_NOT_NONE (C macro)</a></dt> +<dt><a href="c_api.html#SIP_PROTECTED_IS_PUBLIC">SIP_PROTECTED_IS_PUBLIC (C macro)</a></dt> +<dt><a href="specification_files.html#stype-SIP_PYCALLABLE">SIP_PYCALLABLE (SIP type)</a></dt> +<dt><a href="specification_files.html#stype-SIP_PYDICT">SIP_PYDICT (SIP type)</a></dt> +<dt><a href="specification_files.html#stype-SIP_PYLIST">SIP_PYLIST (SIP type)</a></dt> +<dt><a href="specification_files.html#stype-SIP_PYOBJECT">SIP_PYOBJECT (SIP type)</a></dt> +<dt><a href="specification_files.html#stype-SIP_PYSLICE">SIP_PYSLICE (SIP type)</a></dt> +<dt><a href="specification_files.html#stype-SIP_PYTUPLE">SIP_PYTUPLE (SIP type)</a></dt> +<dt><a href="specification_files.html#stype-SIP_PYTYPE">SIP_PYTYPE (SIP type)</a></dt> +<dt><a href="specification_files.html#stype-SIP_QOBJECT">SIP_QOBJECT (SIP type)</a></dt> +<dt><a href="specification_files.html#stype-SIP_RXOBJ_CON">SIP_RXOBJ_CON (SIP type)</a></dt> +<dt><a href="specification_files.html#stype-SIP_RXOBJ_DIS">SIP_RXOBJ_DIS (SIP type)</a></dt> +<dt><a href="specification_files.html#stype-SIP_SIGNAL">SIP_SIGNAL (SIP type)</a></dt> +<dt><a href="specification_files.html#stype-SIP_SLOT">SIP_SLOT (SIP type)</a></dt> +<dt><a href="specification_files.html#stype-SIP_SLOT_CON">SIP_SLOT_CON (SIP type)</a></dt> +<dt><a href="specification_files.html#stype-SIP_SLOT_DIS">SIP_SLOT_DIS (SIP type)</a></dt> +<dt><a href="c_api.html#SIP_SSIZE_T">SIP_SSIZE_T (C macro)</a></dt> +<dt><a href="c_api.html#SIP_UNBLOCK_THREADS">SIP_UNBLOCK_THREADS (C macro)</a></dt> +<dt><a href="c_api.html#SIP_VERSION">SIP_VERSION (C macro)</a></dt> + <dd><dl> + <dt><a href="python_api.html#sip.SIP_VERSION">(in module sip)</a></dt> + </dl></dd> +<dt><a href="build_system.html#sipconfig.Configuration.sip_version">sip_version (sipconfig.Configuration attribute)</a></dt> +<dt><a href="c_api.html#SIP_VERSION_STR">SIP_VERSION_STR (C macro)</a></dt> + <dd><dl> + <dt><a href="python_api.html#sip.SIP_VERSION_STR">(in module sip)</a></dt> + </dl></dd> +<dt><a href="build_system.html#sipconfig.Configuration.sip_version_str">sip_version_str (sipconfig.Configuration attribute)</a></dt> +<dt><a href="c_api.html#sipBadCallableArg">sipBadCallableArg (C function)</a></dt> +<dt><a href="c_api.html#sipBadCatcherResult">sipBadCatcherResult (C function)</a></dt> +<dt><a href="c_api.html#sipBadLengthForSlice">sipBadLengthForSlice (C function)</a></dt> +<dt><a href="c_api.html#sipBuildResult">sipBuildResult (C function)</a></dt> +<dt><a href="c_api.html#sipCallMethod">sipCallMethod (C function)</a></dt> +<dt><a href="c_api.html#sipCanConvertToEnum">sipCanConvertToEnum (C function)</a></dt> +<dt><a href="c_api.html#sipCanConvertToInstance">sipCanConvertToInstance (C function)</a></dt> +<dt><a href="c_api.html#sipCanConvertToMappedType">sipCanConvertToMappedType (C function)</a></dt></dl></td><td width="33%" valign="top"><dl> +<dt><a href="c_api.html#sipCanConvertToType">sipCanConvertToType (C function)</a></dt> +<dt><a href="c_api.html#sipClassName">sipClassName (C function)</a></dt> +<dt><a href="build_system.html#module-sipconfig">sipconfig (module)</a></dt> +<dt><a href="c_api.html#sipConvertFromConstVoidPtr">sipConvertFromConstVoidPtr (C function)</a></dt> +<dt><a href="c_api.html#sipConvertFromConstVoidPtrAndSize">sipConvertFromConstVoidPtrAndSize (C function)</a></dt> +<dt><a href="c_api.html#sipConvertFromEnum">sipConvertFromEnum (C function)</a></dt> +<dt><a href="c_api.html#sipConvertFromInstance">sipConvertFromInstance (C function)</a></dt> +<dt><a href="c_api.html#sipConvertFromMappedType">sipConvertFromMappedType (C function)</a></dt> +<dt><a href="c_api.html#sipConvertFromNamedEnum">sipConvertFromNamedEnum (C function)</a></dt> +<dt><a href="c_api.html#sipConvertFromNewInstance">sipConvertFromNewInstance (C function)</a></dt> +<dt><a href="c_api.html#sipConvertFromNewType">sipConvertFromNewType (C function)</a></dt> +<dt><a href="c_api.html#sipConvertFromSequenceIndex">sipConvertFromSequenceIndex (C function)</a></dt> +<dt><a href="c_api.html#sipConvertFromSliceObject">sipConvertFromSliceObject (C function)</a></dt> +<dt><a href="c_api.html#sipConvertFromType">sipConvertFromType (C function)</a></dt> +<dt><a href="c_api.html#sipConvertFromVoidPtr">sipConvertFromVoidPtr (C function)</a></dt> +<dt><a href="c_api.html#sipConvertFromVoidPtrAndSize">sipConvertFromVoidPtrAndSize (C function)</a></dt> +<dt><a href="c_api.html#sipConvertToInstance">sipConvertToInstance (C function)</a></dt> +<dt><a href="c_api.html#sipConvertToMappedType">sipConvertToMappedType (C function)</a></dt> +<dt><a href="c_api.html#sipConvertToType">sipConvertToType (C function)</a></dt> +<dt><a href="c_api.html#sipConvertToVoidPtr">sipConvertToVoidPtr (C function)</a></dt> +<dt><a href="annotations.html#sipDelayedDtor">sipDelayedDtor (C type)</a></dt> +<dt><a href="annotations.html#sipDelayedDtors">sipDelayedDtors (C function)</a></dt> +<dt><a href="c_api.html#sipExportSymbol">sipExportSymbol (C function)</a></dt> +<dt><a href="c_api.html#sipFindClass">sipFindClass (C function)</a></dt> +<dt><a href="c_api.html#sipFindMappedType">sipFindMappedType (C function)</a></dt> +<dt><a href="c_api.html#sipFindNamedEnum">sipFindNamedEnum (C function)</a></dt> +<dt><a href="c_api.html#sipFindType">sipFindType (C function)</a></dt> +<dt><a href="c_api.html#sipForceConvertToInstance">sipForceConvertToInstance (C function)</a></dt> +<dt><a href="c_api.html#sipForceConvertToMappedType">sipForceConvertToMappedType (C function)</a></dt> +<dt><a href="c_api.html#sipForceConvertToType">sipForceConvertToType (C function)</a></dt> +<dt><a href="c_api.html#sipFree">sipFree (C function)</a></dt> +<dt><a href="c_api.html#sipGetPyObject">sipGetPyObject (C function)</a></dt> +<dt><a href="c_api.html#sipGetState">sipGetState (C function)</a></dt> +<dt><a href="c_api.html#sipGetWrapper">sipGetWrapper (C function)</a></dt> +<dt><a href="c_api.html#sipImportSymbol">sipImportSymbol (C function)</a></dt> +<dt><a href="c_api.html#sipIntTypeClassMap">sipIntTypeClassMap (C type)</a></dt> +<dt><a href="c_api.html#sipIsAPIEnabled">sipIsAPIEnabled (C function)</a></dt> +<dt><a href="c_api.html#sipLong_AsUnsignedLong">sipLong_AsUnsignedLong (C function)</a></dt> +<dt><a href="c_api.html#sipMalloc">sipMalloc (C function)</a></dt> +<dt><a href="c_api.html#sipMapIntToClass">sipMapIntToClass (C function)</a></dt> +<dt><a href="c_api.html#sipMapStringToClass">sipMapStringToClass (C function)</a></dt> +<dt><a href="build_system.html#sipconfig.SIPModuleMakefile">SIPModuleMakefile (class in sipconfig)</a></dt> +<dt><a href="c_api.html#sipParseResult">sipParseResult (C function)</a></dt> +<dt><a href="c_api.html#sipRegisterAttributeGetter">sipRegisterAttributeGetter (C function)</a></dt> +<dt><a href="c_api.html#sipRegisterPyType">sipRegisterPyType (C function)</a></dt> +<dt><a href="c_api.html#sipReleaseInstance">sipReleaseInstance (C function)</a></dt> +<dt><a href="c_api.html#sipReleaseMappedType">sipReleaseMappedType (C function)</a></dt> +<dt><a href="c_api.html#sipReleaseType">sipReleaseType (C function)</a></dt> +<dt><a href="c_api.html#sipResolveTypedef">sipResolveTypedef (C function)</a></dt> +<dt><a href="c_api.html#sipSimpleWrapper">sipSimpleWrapper (C type)</a></dt> +<dt><a href="c_api.html#sipSimpleWrapper_Type">sipSimpleWrapper_Type (C variable)</a></dt> +<dt><a href="c_api.html#sipStringTypeClassMap">sipStringTypeClassMap (C type)</a></dt> +<dt><a href="c_api.html#sipTransferBack">sipTransferBack (C function)</a></dt> +<dt><a href="c_api.html#sipTransferBreak">sipTransferBreak (C function)</a></dt> +<dt><a href="c_api.html#sipTransferTo">sipTransferTo (C function)</a></dt> +<dt><a href="c_api.html#sipTypeAsPyTypeObject">sipTypeAsPyTypeObject (C function)</a></dt> +<dt><a href="c_api.html#sipTypeFromPyTypeObject">sipTypeFromPyTypeObject (C function)</a></dt> +<dt><a href="c_api.html#sipTypeIsClass">sipTypeIsClass (C function)</a></dt> +<dt><a href="c_api.html#sipTypeIsEnum">sipTypeIsEnum (C function)</a></dt> +<dt><a href="c_api.html#sipTypeIsMapped">sipTypeIsMapped (C function)</a></dt> +<dt><a href="c_api.html#sipTypeIsNamespace">sipTypeIsNamespace (C function)</a></dt> +<dt><a href="c_api.html#sipTypeName">sipTypeName (C function)</a></dt> +<dt><a href="c_api.html#sipTypeScope">sipTypeScope (C function)</a></dt> +<dt><a href="c_api.html#sipVoidPtr_Type">sipVoidPtr_Type (C variable)</a></dt> +<dt><a href="c_api.html#sipWrapper">sipWrapper (C type)</a></dt> +<dt><a href="c_api.html#sipWrapper_Check">sipWrapper_Check (C function)</a></dt> +<dt><a href="c_api.html#sipWrapper_Type">sipWrapper_Type (C variable)</a></dt> +<dt><a href="c_api.html#sipWrapperType">sipWrapperType (C type)</a></dt> +<dt><a href="c_api.html#sipWrapperType_Type">sipWrapperType_Type (C variable)</a></dt> +<dt><a href="annotations.html#canno-Supertype">Supertype (class annotation)</a></dt> +</dl></td></tr></table> + +<h2 id="T">T</h2> +<table width="100%" class="indextable"><tr><td width="33%" valign="top"> +<dl> + +<dt><a href="annotations.html#lanno-Timestamp">Timestamp (license annotation)</a></dt> +<dt><a href="annotations.html#aanno-Transfer">Transfer (argument annotation)</a></dt> + <dd><dl> + <dt><a href="annotations.html#fanno-Transfer">(function annotation)</a></dt> + </dl></dd> +<dt><a href="annotations.html#aanno-TransferBack">TransferBack (argument annotation)</a></dt> + <dd><dl> + <dt><a href="annotations.html#fanno-TransferBack">(function annotation)</a></dt> + </dl></dd> +<dt><a href="python_api.html#sip.transferback">transferback() (in module sip)</a></dt> +<dt><a href="annotations.html#aanno-TransferThis">TransferThis (argument annotation)</a></dt> + <dd><dl> + <dt><a href="annotations.html#fanno-TransferThis">(function annotation)</a></dt> + </dl></dd></dl></td><td width="33%" valign="top"><dl> +<dt><a href="python_api.html#sip.transferto">transferto() (in module sip)</a></dt> +<dt><a href="annotations.html#lanno-Type">Type (license annotation)</a></dt> +<dt><a href="c_api.html#typeInt">typeInt (C member)</a></dt> +<dt><a href="c_api.html#typeString">typeString (C member)</a></dt> +</dl></td></tr></table> + +<h2 id="U">U</h2> +<table width="100%" class="indextable"><tr><td width="33%" valign="top"> +<dl> + +<dt><a href="build_system.html#sipconfig.Configuration.universal">universal (sipconfig.Configuration attribute)</a></dt> +<dt><a href="python_api.html#sip.unwrapinstance">unwrapinstance() (in module sip)</a></dt></dl></td><td width="33%" valign="top"><dl> +<dt><a href="c_api.html#user">user (C member)</a></dt> +</dl></td></tr></table> + +<h2 id="V">V</h2> +<table width="100%" class="indextable"><tr><td width="33%" valign="top"> +<dl> + +<dt><a href="build_system.html#sipconfig.version_to_sip_tag">version_to_sip_tag() (in module sipconfig)</a></dt> +<dt><a href="build_system.html#sipconfig.version_to_string">version_to_string() (in module sipconfig)</a></dt></dl></td><td width="33%" valign="top"><dl> +<dt><a href="python_api.html#sip.voidptr">voidptr (class in sip)</a></dt> +</dl></td></tr></table> + +<h2 id="W">W</h2> +<table width="100%" class="indextable"><tr><td width="33%" valign="top"> +<dl> + +<dt><a href="python_api.html#sip.wrapinstance">wrapinstance() (in module sip)</a></dt> +<dt><a href="python_api.html#sip.wrapper">wrapper (class in sip)</a></dt></dl></td><td width="33%" valign="top"><dl> +<dt><a href="python_api.html#sip.wrappertype">wrappertype (class in sip)</a></dt> +</dl></td></tr></table> + + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + + + + <div id="searchbox" style="display: none"> + <h3>Quick search</h3> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" size="18" /> + <input type="submit" value="Go" /> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </form> + <p class="searchtip" style="font-size: 90%"> + Enter search terms or a module, class or function name. + </p> + </div> + <script type="text/javascript">$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="#" title="General Index" + >index</a></li> + <li class="right" > + <a href="modindex.html" title="Global Module Index" + >modules</a> |</li> + <li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2010 Riverbank Computing Limited. + Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.4. + </div> + </body> +</html>
\ No newline at end of file diff --git a/doc/html/incompatibilities.html b/doc/html/incompatibilities.html new file mode 100644 index 0000000..1663016 --- /dev/null +++ b/doc/html/incompatibilities.html @@ -0,0 +1,281 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + + <title>Potential Incompatibilities with Earlier Versions — SIP 4.10.5 Reference Guide</title> + <link rel="stylesheet" href="_static/default.css" type="text/css" /> + <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '#', + VERSION: '4.10.5', + COLLAPSE_MODINDEX: false, + FILE_SUFFIX: '.html', + HAS_SOURCE: true + }; + </script> + <script type="text/javascript" src="_static/jquery.js"></script> + <script type="text/javascript" src="_static/doctools.js"></script> + <link rel="top" title="SIP 4.10.5 Reference Guide" href="index.html" /> + <link rel="next" title="Installation" href="installation.html" /> + <link rel="prev" title="Introduction" href="introduction.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="modindex.html" title="Global Module Index" + accesskey="M">modules</a> |</li> + <li class="right" > + <a href="installation.html" title="Installation" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="introduction.html" title="Introduction" + accesskey="P">previous</a> |</li> + <li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="potential-incompatibilities-with-earlier-versions"> +<h1>Potential Incompatibilities with Earlier Versions<a class="headerlink" href="#potential-incompatibilities-with-earlier-versions" title="Permalink to this headline">¶</a></h1> +<p>This section describes incompatibilities introduced by particular versions of +SIP. Normally these are the removal of previously deprecated features.</p> +<div class="section" id="sip-v4-10-1"> +<h2>SIP v4.10.1<a class="headerlink" href="#sip-v4-10-1" title="Permalink to this headline">¶</a></h2> +<div class="section" id="newly-deprecated-features"> +<h3>Newly Deprecated Features<a class="headerlink" href="#newly-deprecated-features" title="Permalink to this headline">¶</a></h3> +<p>The following parts of the <a class="reference external" href="c_api.html#ref-c-api"><em>C API</em></a> are now deprecated (but +still supported).</p> +<ul class="simple"> +<li>The <tt class="docutils literal"><span class="pre">D</span></tt> format character of <a title="sipParseResult" class="reference external" href="c_api.html#sipParseResult"><tt class="xref docutils literal"><span class="pre">sipParseResult()</span></tt></a>.</li> +</ul> +</div> +</div> +<div class="section" id="sip-v4-8"> +<h2>SIP v4.8<a class="headerlink" href="#sip-v4-8" title="Permalink to this headline">¶</a></h2> +<div class="section" id="truediv"> +<h3>__truediv__<a class="headerlink" href="#truediv" title="Permalink to this headline">¶</a></h3> +<p>Prior to this version the <tt class="xref docutils literal"><span class="pre">__div__()</span></tt> special method implicitly defined the +<tt class="xref docutils literal"><span class="pre">__truediv__()</span></tt> special method. From this version the <tt class="xref docutils literal"><span class="pre">__truediv__()</span></tt> +special method must be explicitly defined.</p> +</div> +<div class="section" id="sipwrapper-user-member"> +<h3>sipWrapper user Member<a class="headerlink" href="#sipwrapper-user-member" title="Permalink to this headline">¶</a></h3> +<p>Prior to this version the <a title="sipWrapper" class="reference external" href="c_api.html#sipWrapper"><tt class="xref docutils literal"><span class="pre">sipWrapper</span></tt></a> structure had a member called +<a title="user" class="reference external" href="c_api.html#user"><tt class="xref docutils literal"><span class="pre">user</span></tt></a> which is available for handwritten code to use. From this +version <a title="user" class="reference external" href="c_api.html#user"><tt class="xref docutils literal"><span class="pre">user</span></tt></a> is a member of the <a title="sipSimpleWrapper" class="reference external" href="c_api.html#sipSimpleWrapper"><tt class="xref docutils literal"><span class="pre">sipSimpleWrapper</span></tt></a> structure.</p> +<p><a title="sipWrapper" class="reference external" href="c_api.html#sipWrapper"><tt class="xref docutils literal"><span class="pre">sipWrapper</span></tt></a> pointers can be safely cast to <a title="sipSimpleWrapper" class="reference external" href="c_api.html#sipSimpleWrapper"><tt class="xref docutils literal"><span class="pre">sipSimpleWrapper</span></tt></a> +pointers, so if your code does something like:</p> +<div class="highlight-python"><pre>((sipWrapper *)obj)->user = an_object_reference;</pre> +</div> +<p>then you just need to change it to:</p> +<div class="highlight-python"><pre>((sipSimpleWrapper *)obj)->user = an_object_reference;</pre> +</div> +</div> +<div class="section" id="removal-of-previously-deprecated-features"> +<h3>Removal of Previously Deprecated Features<a class="headerlink" href="#removal-of-previously-deprecated-features" title="Permalink to this headline">¶</a></h3> +<p>The following parts of the <a class="reference external" href="c_api.html#ref-c-api"><em>C API</em></a> have been removed.</p> +<ul class="simple"> +<li>The <tt class="docutils literal"><span class="pre">a</span></tt>, <tt class="docutils literal"><span class="pre">A</span></tt>, <tt class="docutils literal"><span class="pre">M</span></tt>, <tt class="docutils literal"><span class="pre">N</span></tt>, <tt class="docutils literal"><span class="pre">O</span></tt>, <tt class="docutils literal"><span class="pre">P</span></tt> and <tt class="docutils literal"><span class="pre">T</span></tt> format characters +from <a title="sipBuildResult" class="reference external" href="c_api.html#sipBuildResult"><tt class="xref docutils literal"><span class="pre">sipBuildResult()</span></tt></a> and <a title="sipCallMethod" class="reference external" href="c_api.html#sipCallMethod"><tt class="xref docutils literal"><span class="pre">sipCallMethod()</span></tt></a>.</li> +<li>The <tt class="docutils literal"><span class="pre">a</span></tt>, <tt class="docutils literal"><span class="pre">A</span></tt>, <tt class="docutils literal"><span class="pre">L</span></tt> and <tt class="docutils literal"><span class="pre">M</span></tt> format characters from +<a title="sipParseResult" class="reference external" href="c_api.html#sipParseResult"><tt class="xref docutils literal"><span class="pre">sipParseResult()</span></tt></a>.</li> +<li><tt class="xref docutils literal"><span class="pre">sipConvertToCpp()</span></tt></li> +<li><tt class="xref docutils literal"><span class="pre">sipIsSubClassInstance()</span></tt></li> +<li><tt class="xref docutils literal"><span class="pre">sipTransfer()</span></tt></li> +<li>The <tt class="xref docutils literal"><span class="pre">transfer()</span></tt> function of the <a title="" class="reference external" href="python_api.html#module-sip"><tt class="xref docutils literal"><span class="pre">sip</span></tt></a> module.</li> +<li>The old-style generated type convertors.</li> +</ul> +<p>In addition the <a class="reference external" href="command_line.html#cmdoption-sip-a"><em class="xref">-a</em></a> command line option to <tt class="docutils literal"><span class="pre">configure.py</span></tt> has +been removed.</p> +</div> +<div class="section" id="removal-of-pyqt-specific-features"> +<h3>Removal of PyQt-specific Features<a class="headerlink" href="#removal-of-pyqt-specific-features" title="Permalink to this headline">¶</a></h3> +<p>The following PyQt-specific support functions have been removed.</p> +<ul class="simple"> +<li><tt class="xref docutils literal"><span class="pre">sipConnectRx()</span></tt></li> +<li><tt class="xref docutils literal"><span class="pre">sipDisconnectRx()</span></tt></li> +<li><tt class="xref docutils literal"><span class="pre">sipEmitSlot()</span></tt></li> +<li><tt class="xref docutils literal"><span class="pre">sipGetSender()</span></tt></li> +</ul> +</div> +<div class="section" id="id1"> +<h3>Newly Deprecated Features<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3> +<p>The following parts of the <a class="reference external" href="c_api.html#ref-c-api"><em>C API</em></a> are now deprecated (but +still supported).</p> +<ul class="simple"> +<li>The <a class="reference external" href="c_api.html#ref-type-objects"><em>Generated Type Objects</em></a>.</li> +<li>The <a class="reference external" href="c_api.html#ref-enum-type-objects"><em>Generated Named Enum Type Objects</em></a>.</li> +<li><a title="sipConvertFromInstance" class="reference external" href="c_api.html#sipConvertFromInstance"><tt class="xref docutils literal"><span class="pre">sipConvertFromInstance()</span></tt></a></li> +<li><a title="sipConvertFromMappedType" class="reference external" href="c_api.html#sipConvertFromMappedType"><tt class="xref docutils literal"><span class="pre">sipConvertFromMappedType()</span></tt></a></li> +<li><a title="sipConvertFromNamedEnum" class="reference external" href="c_api.html#sipConvertFromNamedEnum"><tt class="xref docutils literal"><span class="pre">sipConvertFromNamedEnum()</span></tt></a></li> +<li><a title="sipConvertFromNewInstance" class="reference external" href="c_api.html#sipConvertFromNewInstance"><tt class="xref docutils literal"><span class="pre">sipConvertFromNewInstance()</span></tt></a></li> +<li><a title="sipCanConvertToInstance" class="reference external" href="c_api.html#sipCanConvertToInstance"><tt class="xref docutils literal"><span class="pre">sipCanConvertToInstance()</span></tt></a></li> +<li><a title="sipCanConvertToMappedType" class="reference external" href="c_api.html#sipCanConvertToMappedType"><tt class="xref docutils literal"><span class="pre">sipCanConvertToMappedType()</span></tt></a></li> +<li><a title="sipConvertToInstance" class="reference external" href="c_api.html#sipConvertToInstance"><tt class="xref docutils literal"><span class="pre">sipConvertToInstance()</span></tt></a></li> +<li><a title="sipConvertToMappedType" class="reference external" href="c_api.html#sipConvertToMappedType"><tt class="xref docutils literal"><span class="pre">sipConvertToMappedType()</span></tt></a></li> +<li><a title="sipForceConvertToInstance" class="reference external" href="c_api.html#sipForceConvertToInstance"><tt class="xref docutils literal"><span class="pre">sipForceConvertToInstance()</span></tt></a></li> +<li><a title="sipForceConvertToMappedType" class="reference external" href="c_api.html#sipForceConvertToMappedType"><tt class="xref docutils literal"><span class="pre">sipForceConvertToMappedType()</span></tt></a></li> +<li><a title="sipClassName" class="reference external" href="c_api.html#sipClassName"><tt class="xref docutils literal"><span class="pre">sipClassName()</span></tt></a></li> +<li><a title="sipFindClass" class="reference external" href="c_api.html#sipFindClass"><tt class="xref docutils literal"><span class="pre">sipFindClass()</span></tt></a></li> +<li><a title="sipFindNamedEnum" class="reference external" href="c_api.html#sipFindNamedEnum"><tt class="xref docutils literal"><span class="pre">sipFindNamedEnum()</span></tt></a></li> +<li><a title="sipFindMappedType" class="reference external" href="c_api.html#sipFindMappedType"><tt class="xref docutils literal"><span class="pre">sipFindMappedType()</span></tt></a></li> +<li><a title="sipGetWrapper" class="reference external" href="c_api.html#sipGetWrapper"><tt class="xref docutils literal"><span class="pre">sipGetWrapper()</span></tt></a></li> +<li><a title="sipReleaseInstance" class="reference external" href="c_api.html#sipReleaseInstance"><tt class="xref docutils literal"><span class="pre">sipReleaseInstance()</span></tt></a></li> +<li><a title="sipReleaseMappedType" class="reference external" href="c_api.html#sipReleaseMappedType"><tt class="xref docutils literal"><span class="pre">sipReleaseMappedType()</span></tt></a></li> +<li><a title="sipWrapper_Check" class="reference external" href="c_api.html#sipWrapper_Check"><tt class="xref docutils literal"><span class="pre">sipWrapper_Check()</span></tt></a></li> +<li>The <tt class="docutils literal"><span class="pre">B</span></tt>, <tt class="docutils literal"><span class="pre">C</span></tt> and <tt class="docutils literal"><span class="pre">E</span></tt> format characters of <a title="sipBuildResult" class="reference external" href="c_api.html#sipBuildResult"><tt class="xref docutils literal"><span class="pre">sipBuildResult()</span></tt></a> and +<a title="sipCallMethod" class="reference external" href="c_api.html#sipCallMethod"><tt class="xref docutils literal"><span class="pre">sipCallMethod()</span></tt></a>.</li> +<li>The <tt class="docutils literal"><span class="pre">s</span></tt>, <tt class="docutils literal"><span class="pre">C</span></tt> and <tt class="docutils literal"><span class="pre">E</span></tt> format characters of <a title="sipParseResult" class="reference external" href="c_api.html#sipParseResult"><tt class="xref docutils literal"><span class="pre">sipParseResult()</span></tt></a>.</li> +</ul> +</div> +</div> +<div class="section" id="sip-v4-7-8"> +<h2>SIP v4.7.8<a class="headerlink" href="#sip-v4-7-8" title="Permalink to this headline">¶</a></h2> +<div class="section" id="automatic-int-to-enum-conversions"> +<h3>Automatic int to Enum Conversions<a class="headerlink" href="#automatic-int-to-enum-conversions" title="Permalink to this headline">¶</a></h3> +<p>This version allows a Python <tt class="docutils literal"><span class="pre">int</span></tt> 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.</p> +<p>The <a class="reference external" href="annotations.html#aanno-Constrained"><tt class="xref docutils literal"><span class="pre">Constrained</span></tt></a> argument annotation can now be applied to an enum +argument to revert to the earlier behaviour.</p> +</div> +</div> +<div class="section" id="sip-v4-7-3"> +<h2>SIP v4.7.3<a class="headerlink" href="#sip-v4-7-3" title="Permalink to this headline">¶</a></h2> +<div class="section" id="complementary-comparison-operators"> +<h3>Complementary Comparison Operators<a class="headerlink" href="#complementary-comparison-operators" title="Permalink to this headline">¶</a></h3> +<p>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.</p> +<p>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.</p> +</div> +</div> +<div class="section" id="sip-v4-4"> +<h2>SIP v4.4<a class="headerlink" href="#sip-v4-4" title="Permalink to this headline">¶</a></h2> +<div class="section" id="convertfromtypecode-and-converttotypecode"> +<h3>%ConvertFromTypeCode and %ConvertToTypeCode<a class="headerlink" href="#convertfromtypecode-and-converttotypecode" title="Permalink to this headline">¶</a></h3> +<p>Handwritten <a class="reference external" href="directives.html#directive-%ConvertFromTypeCode"><tt class="xref docutils literal"><span class="pre">%ConvertFromTypeCode</span></tt></a> and +<a class="reference external" href="directives.html#directive-%ConvertToTypeCode"><tt class="xref docutils literal"><span class="pre">%ConvertToTypeCode</span></tt></a> now have the responsibility for implementing +the <a class="reference external" href="annotations.html#aanno-Transfer"><tt class="xref docutils literal"><span class="pre">Transfer</span></tt></a> and <a class="reference external" href="annotations.html#aanno-TransferBack"><tt class="xref docutils literal"><span class="pre">TransferBack</span></tt></a> annotations.</p> +</div> +<div class="section" id="sip-build"> +<h3>SIP_BUILD<a class="headerlink" href="#sip-build" title="Permalink to this headline">¶</a></h3> +<p>The <tt class="xref docutils literal"><span class="pre">SIP_BUILD</span></tt> C preprocessor symbol has been removed.</p> +</div> +<div class="section" id="id2"> +<h3>Newly Deprecated Features<a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h3> +<p>The following parts of the <a class="reference external" href="c_api.html#ref-c-api"><em>C API</em></a> are now deprecated (but +still supported).</p> +<ul class="simple"> +<li>The old-style generated type convertors.</li> +<li><tt class="xref docutils literal"><span class="pre">sipConvertToCpp()</span></tt></li> +<li><tt class="xref docutils literal"><span class="pre">sipIsSubClassInstance()</span></tt></li> +</ul> +</div> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference external" href="#">Potential Incompatibilities with Earlier Versions</a><ul> +<li><a class="reference external" href="#sip-v4-10-1">SIP v4.10.1</a><ul> +<li><a class="reference external" href="#newly-deprecated-features">Newly Deprecated Features</a></li> +</ul> +</li> +<li><a class="reference external" href="#sip-v4-8">SIP v4.8</a><ul> +<li><a class="reference external" href="#truediv">__truediv__</a></li> +<li><a class="reference external" href="#sipwrapper-user-member">sipWrapper user Member</a></li> +<li><a class="reference external" href="#removal-of-previously-deprecated-features">Removal of Previously Deprecated Features</a></li> +<li><a class="reference external" href="#removal-of-pyqt-specific-features">Removal of PyQt-specific Features</a></li> +<li><a class="reference external" href="#id1">Newly Deprecated Features</a></li> +</ul> +</li> +<li><a class="reference external" href="#sip-v4-7-8">SIP v4.7.8</a><ul> +<li><a class="reference external" href="#automatic-int-to-enum-conversions">Automatic int to Enum Conversions</a></li> +</ul> +</li> +<li><a class="reference external" href="#sip-v4-7-3">SIP v4.7.3</a><ul> +<li><a class="reference external" href="#complementary-comparison-operators">Complementary Comparison Operators</a></li> +</ul> +</li> +<li><a class="reference external" href="#sip-v4-4">SIP v4.4</a><ul> +<li><a class="reference external" href="#convertfromtypecode-and-converttotypecode">%ConvertFromTypeCode and %ConvertToTypeCode</a></li> +<li><a class="reference external" href="#sip-build">SIP_BUILD</a></li> +<li><a class="reference external" href="#id2">Newly Deprecated Features</a></li> +</ul> +</li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="introduction.html" + title="previous chapter">Introduction</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="installation.html" + title="next chapter">Installation</a></p> + <div id="searchbox" style="display: none"> + <h3>Quick search</h3> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" size="18" /> + <input type="submit" value="Go" /> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </form> + <p class="searchtip" style="font-size: 90%"> + Enter search terms or a module, class or function name. + </p> + </div> + <script type="text/javascript">$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="modindex.html" title="Global Module Index" + >modules</a> |</li> + <li class="right" > + <a href="installation.html" title="Installation" + >next</a> |</li> + <li class="right" > + <a href="introduction.html" title="Introduction" + >previous</a> |</li> + <li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2010 Riverbank Computing Limited. + Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.4. + </div> + </body> +</html>
\ No newline at end of file diff --git a/doc/html/index.html b/doc/html/index.html new file mode 100644 index 0000000..ed2d37d --- /dev/null +++ b/doc/html/index.html @@ -0,0 +1,167 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + + <title>SIP Reference Guide — SIP 4.10.5 Reference Guide</title> + <link rel="stylesheet" href="_static/default.css" type="text/css" /> + <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '#', + VERSION: '4.10.5', + COLLAPSE_MODINDEX: false, + FILE_SUFFIX: '.html', + HAS_SOURCE: true + }; + </script> + <script type="text/javascript" src="_static/jquery.js"></script> + <script type="text/javascript" src="_static/doctools.js"></script> + <link rel="top" title="SIP 4.10.5 Reference Guide" href="#" /> + <link rel="next" title="Introduction" href="introduction.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="modindex.html" title="Global Module Index" + accesskey="M">modules</a> |</li> + <li class="right" > + <a href="introduction.html" title="Introduction" + accesskey="N">next</a> |</li> + <li><a href="#">SIP 4.10.5 Reference Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="sip-reference-guide"> +<h1>SIP Reference Guide<a class="headerlink" href="#sip-reference-guide" title="Permalink to this headline">¶</a></h1> +<ul> +<li class="toctree-l1"><a class="reference external" href="introduction.html">Introduction</a><ul> +<li class="toctree-l2"><a class="reference external" href="introduction.html#license">License</a></li> +<li class="toctree-l2"><a class="reference external" href="introduction.html#features">Features</a></li> +<li class="toctree-l2"><a class="reference external" href="introduction.html#sip-components">SIP Components</a></li> +<li class="toctree-l2"><a class="reference external" href="introduction.html#qt-support">Qt Support</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference external" href="incompatibilities.html">Potential Incompatibilities with Earlier Versions</a><ul> +<li class="toctree-l2"><a class="reference external" href="incompatibilities.html#sip-v4-10-1">SIP v4.10.1</a></li> +<li class="toctree-l2"><a class="reference external" href="incompatibilities.html#sip-v4-8">SIP v4.8</a></li> +<li class="toctree-l2"><a class="reference external" href="incompatibilities.html#sip-v4-7-8">SIP v4.7.8</a></li> +<li class="toctree-l2"><a class="reference external" href="incompatibilities.html#sip-v4-7-3">SIP v4.7.3</a></li> +<li class="toctree-l2"><a class="reference external" href="incompatibilities.html#sip-v4-4">SIP v4.4</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference external" href="installation.html">Installation</a><ul> +<li class="toctree-l2"><a class="reference external" href="installation.html#downloading">Downloading</a></li> +<li class="toctree-l2"><a class="reference external" href="installation.html#configuring">Configuring</a></li> +<li class="toctree-l2"><a class="reference external" href="installation.html#building">Building</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference external" href="using.html">Using SIP</a><ul> +<li class="toctree-l2"><a class="reference external" href="using.html#a-simple-c-example">A Simple C++ Example</a></li> +<li class="toctree-l2"><a class="reference external" href="using.html#id7">A Simple C Example</a></li> +<li class="toctree-l2"><a class="reference external" href="using.html#a-more-complex-c-example">A More Complex C++ Example</a></li> +<li class="toctree-l2"><a class="reference external" href="using.html#ownership-of-objects">Ownership of Objects</a></li> +<li class="toctree-l2"><a class="reference external" href="using.html#types-and-meta-types">Types and Meta-types</a></li> +<li class="toctree-l2"><a class="reference external" href="using.html#lazy-type-attributes">Lazy Type Attributes</a></li> +<li class="toctree-l2"><a class="reference external" href="using.html#support-for-python-s-buffer-interface">Support for Python’s Buffer Interface</a></li> +<li class="toctree-l2"><a class="reference external" href="using.html#support-for-wide-characters">Support for Wide Characters</a></li> +<li class="toctree-l2"><a class="reference external" href="using.html#the-python-global-interpreter-lock">The Python Global Interpreter Lock</a></li> +<li class="toctree-l2"><a class="reference external" href="using.html#managing-incompatible-apis">Managing Incompatible APIs</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference external" href="command_line.html">The SIP Command Line</a></li> +<li class="toctree-l1"><a class="reference external" href="specification_files.html">SIP Specification Files</a><ul> +<li class="toctree-l2"><a class="reference external" href="specification_files.html#syntax-definition">Syntax Definition</a></li> +<li class="toctree-l2"><a class="reference external" href="specification_files.html#variable-numbers-of-arguments">Variable Numbers of Arguments</a></li> +<li class="toctree-l2"><a class="reference external" href="specification_files.html#additional-sip-types">Additional SIP Types</a></li> +<li class="toctree-l2"><a class="reference external" href="specification_files.html#classic-division-and-true-division">Classic Division and True Division</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference external" href="directives.html">Directives</a></li> +<li class="toctree-l1"><a class="reference external" href="annotations.html">Annotations</a><ul> +<li class="toctree-l2"><a class="reference external" href="annotations.html#argument-annotations">Argument Annotations</a></li> +<li class="toctree-l2"><a class="reference external" href="annotations.html#class-annotations">Class Annotations</a></li> +<li class="toctree-l2"><a class="reference external" href="annotations.html#mapped-type-annotations">Mapped Type Annotations</a></li> +<li class="toctree-l2"><a class="reference external" href="annotations.html#enum-annotations">Enum Annotations</a></li> +<li class="toctree-l2"><a class="reference external" href="annotations.html#exception-annotations">Exception Annotations</a></li> +<li class="toctree-l2"><a class="reference external" href="annotations.html#function-annotations">Function Annotations</a></li> +<li class="toctree-l2"><a class="reference external" href="annotations.html#license-annotations">License Annotations</a></li> +<li class="toctree-l2"><a class="reference external" href="annotations.html#typedef-annotations">Typedef Annotations</a></li> +<li class="toctree-l2"><a class="reference external" href="annotations.html#variable-annotations">Variable Annotations</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference external" href="c_api.html">C API for Handwritten Code</a><ul> +<li class="toctree-l2"><a class="reference external" href="c_api.html#generated-type-structures">Generated Type Structures</a></li> +<li class="toctree-l2"><a class="reference external" href="c_api.html#generated-type-objects">Generated Type Objects</a></li> +<li class="toctree-l2"><a class="reference external" href="c_api.html#generated-named-enum-type-objects">Generated Named Enum Type Objects</a></li> +<li class="toctree-l2"><a class="reference external" href="c_api.html#generated-derived-classes">Generated Derived Classes</a></li> +<li class="toctree-l2"><a class="reference external" href="c_api.html#generated-exception-objects">Generated Exception Objects</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference external" href="embedding.html">Using the C API when Embedding</a></li> +<li class="toctree-l1"><a class="reference external" href="python_api.html">Python API for Applications</a></li> +<li class="toctree-l1"><a class="reference external" href="build_system.html">The Build System</a></li> +<li class="toctree-l1"><a class="reference external" href="distutils.html">Building Your Extension with distutils</a></li> +<li class="toctree-l1"><a class="reference external" href="builtin.html">Builtin Modules and Custom Interpreters</a></li> +</ul> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h4>Next topic</h4> + <p class="topless"><a href="introduction.html" + title="next chapter">Introduction</a></p> + <div id="searchbox" style="display: none"> + <h3>Quick search</h3> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" size="18" /> + <input type="submit" value="Go" /> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </form> + <p class="searchtip" style="font-size: 90%"> + Enter search terms or a module, class or function name. + </p> + </div> + <script type="text/javascript">$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="modindex.html" title="Global Module Index" + >modules</a> |</li> + <li class="right" > + <a href="introduction.html" title="Introduction" + >next</a> |</li> + <li><a href="#">SIP 4.10.5 Reference Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2010 Riverbank Computing Limited. + Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.4. + </div> + </body> +</html>
\ No newline at end of file diff --git a/doc/html/installation.html b/doc/html/installation.html new file mode 100644 index 0000000..0769a36 --- /dev/null +++ b/doc/html/installation.html @@ -0,0 +1,277 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + + <title>Installation — SIP 4.10.5 Reference Guide</title> + <link rel="stylesheet" href="_static/default.css" type="text/css" /> + <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '#', + VERSION: '4.10.5', + COLLAPSE_MODINDEX: false, + FILE_SUFFIX: '.html', + HAS_SOURCE: true + }; + </script> + <script type="text/javascript" src="_static/jquery.js"></script> + <script type="text/javascript" src="_static/doctools.js"></script> + <link rel="top" title="SIP 4.10.5 Reference Guide" href="index.html" /> + <link rel="next" title="Using SIP" href="using.html" /> + <link rel="prev" title="Potential Incompatibilities with Earlier Versions" href="incompatibilities.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="modindex.html" title="Global Module Index" + accesskey="M">modules</a> |</li> + <li class="right" > + <a href="using.html" title="Using SIP" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="incompatibilities.html" title="Potential Incompatibilities with Earlier Versions" + accesskey="P">previous</a> |</li> + <li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="installation"> +<h1>Installation<a class="headerlink" href="#installation" title="Permalink to this headline">¶</a></h1> +<div class="section" id="downloading"> +<h2>Downloading<a class="headerlink" href="#downloading" title="Permalink to this headline">¶</a></h2> +<p>You can get the latest release of the SIP source code from +<a class="reference external" href="http://www.riverbankcomputing.com/software/sip/download">http://www.riverbankcomputing.com/software/sip/download</a>.</p> +<p>SIP is also included with all of the major Linux distributions. However, it +may be a version or two out of date.</p> +</div> +<div class="section" id="configuring"> +<h2>Configuring<a class="headerlink" href="#configuring" title="Permalink to this headline">¶</a></h2> +<p>After unpacking the source package (either a <tt class="docutils literal"><span class="pre">.tar.gz</span></tt> or a <tt class="docutils literal"><span class="pre">.zip</span></tt> file +depending on your platform) you should then check for any <tt class="docutils literal"><span class="pre">README</span></tt> files +that relate to your platform.</p> +<p>Next you need to configure SIP by executing the <tt class="docutils literal"><span class="pre">configure.py</span></tt> script. For +example:</p> +<div class="highlight-python"><pre>python configure.py</pre> +</div> +<p>This assumes that the Python interpreter is on your path. Something like the +following may be appropriate on Windows:</p> +<div class="highlight-python"><pre>c:\python26\python configure.py</pre> +</div> +<p>If you have multiple versions of Python installed then make sure you use the +interpreter for which you wish SIP to generate bindings for.</p> +<p>The full set of command line options is:</p> +<dl class="cmdoption"> +<dt id="cmdoption-configure.py--version"> +<tt class="descname">--version</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-configure.py--version" title="Permalink to this definition">¶</a></dt> +<dd>Display the SIP version number.</dd></dl> + +<dl class="cmdoption"> +<dt id="cmdoption-configure.py-h"> +<tt class="descname">-h</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--help</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-configure.py-h" title="Permalink to this definition">¶</a></dt> +<dd>Display a help message.</dd></dl> + +<dl class="cmdoption"> +<dt id="cmdoption-configure.py--arch"> +<tt class="descname">--arch</tt><tt class="descclassname"> <ARCH></tt><a class="headerlink" href="#cmdoption-configure.py--arch" title="Permalink to this definition">¶</a></dt> +<dd>Binaries for the MacOS/X architecture <tt class="docutils literal"><span class="pre"><ARCH></span></tt> 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.</dd></dl> + +<dl class="cmdoption"> +<dt id="cmdoption-configure.py-b"> +<tt class="descname">-b</tt><tt class="descclassname"> <DIR></tt><tt class="descclassname">, </tt><tt class="descname">--bindir</tt><tt class="descclassname"> <DIR></tt><a class="headerlink" href="#cmdoption-configure.py-b" title="Permalink to this definition">¶</a></dt> +<dd>The SIP code generator will be installed in the directory <tt class="docutils literal"><span class="pre"><DIR></span></tt>.</dd></dl> + +<dl class="cmdoption"> +<dt id="cmdoption-configure.py-d"> +<tt class="descname">-d</tt><tt class="descclassname"> <DIR></tt><tt class="descclassname">, </tt><tt class="descname">--destdir</tt><tt class="descclassname"> <DIR></tt><a class="headerlink" href="#cmdoption-configure.py-d" title="Permalink to this definition">¶</a></dt> +<dd>The SIP module will be installed in the directory <tt class="docutils literal"><span class="pre"><DIR></span></tt>.</dd></dl> + +<dl class="cmdoption"> +<dt id="cmdoption-configure.py-e"> +<tt class="descname">-e</tt><tt class="descclassname"> <DIR></tt><tt class="descclassname">, </tt><tt class="descname">--incdir</tt><tt class="descclassname"> <DIR></tt><a class="headerlink" href="#cmdoption-configure.py-e" title="Permalink to this definition">¶</a></dt> +<dd>The SIP header file will be installed in the directory <tt class="docutils literal"><span class="pre"><DIR></span></tt>.</dd></dl> + +<dl class="cmdoption"> +<dt id="cmdoption-configure.py-k"> +<tt class="descname">-k</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--static</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-configure.py-k" title="Permalink to this definition">¶</a></dt> +<dd>The SIP module will be built as a static library. This is useful when +building the SIP module as a Python builtin (see <a class="reference external" href="builtin.html#ref-builtin"><em>Builtin Modules and Custom Interpreters</em></a>).</dd></dl> + +<dl class="cmdoption"> +<dt id="cmdoption-configure.py-n"> +<tt class="descname">-n</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--universal</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-configure.py-n" title="Permalink to this definition">¶</a></dt> +<dd>The SIP code generator and module will be built as universal binaries +under MacOS/X. If the <a class="reference internal" href="#cmdoption-configure.py--arch"><em class="xref">--arch</em></a> option has +not been specified then the universal binary will include the <tt class="docutils literal"><span class="pre">i386</span></tt> and +<tt class="docutils literal"><span class="pre">ppc</span></tt> architectures.</dd></dl> + +<dl class="cmdoption"> +<dt id="cmdoption-configure.py-p"> +<tt class="descname">-p</tt><tt class="descclassname"> <PLATFORM></tt><tt class="descclassname">, </tt><tt class="descname">--platform</tt><tt class="descclassname"> <PLATFORM></tt><a class="headerlink" href="#cmdoption-configure.py-p" title="Permalink to this definition">¶</a></dt> +<dd>Explicitly specify the platform/compiler to be used by the build system, +otherwise a platform specific default will be used. The +<a class="reference internal" href="#cmdoption-configure.py--show-platforms"><em class="xref">--show-platforms</em></a> option will +display all the supported platform/compilers.</dd></dl> + +<dl class="cmdoption"> +<dt id="cmdoption-configure.py-s"> +<tt class="descname">-s</tt><tt class="descclassname"> <SDK></tt><tt class="descclassname">, </tt><tt class="descname">--sdk</tt><tt class="descclassname"> <SDK></tt><a class="headerlink" href="#cmdoption-configure.py-s" title="Permalink to this definition">¶</a></dt> +<dd>If the <a class="reference internal" href="#cmdoption-configure.py-n"><em class="xref">--universal</em></a> 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 <tt class="docutils literal"><span class="pre">/Developer/SDKs</span></tt>.</dd></dl> + +<dl class="cmdoption"> +<dt id="cmdoption-configure.py-u"> +<tt class="descname">-u</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--debug</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-configure.py-u" title="Permalink to this definition">¶</a></dt> +<dd>The SIP module will be built with debugging symbols.</dd></dl> + +<dl class="cmdoption"> +<dt id="cmdoption-configure.py-v"> +<tt class="descname">-v</tt><tt class="descclassname"> <DIR></tt><tt class="descclassname">, </tt><tt class="descname">--sipdir</tt><tt class="descclassname"> <DIR></tt><a class="headerlink" href="#cmdoption-configure.py-v" title="Permalink to this definition">¶</a></dt> +<dd>By default <tt class="docutils literal"><span class="pre">.sip</span></tt> files will be installed in the directory <tt class="docutils literal"><span class="pre"><DIR></span></tt>.</dd></dl> + +<dl class="cmdoption"> +<dt id="cmdoption-configure.py--show-platforms"> +<tt class="descname">--show-platforms</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-configure.py--show-platforms" title="Permalink to this definition">¶</a></dt> +<dd>The list of all supported platform/compilers will be displayed.</dd></dl> + +<dl class="cmdoption"> +<dt id="cmdoption-configure.py--show-build-macros"> +<tt class="descname">--show-build-macros</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-configure.py--show-build-macros" title="Permalink to this definition">¶</a></dt> +<dd>The list of all available build macros will be displayed.</dd></dl> + +<p>The <tt class="docutils literal"><span class="pre">configure.py</span></tt> script takes many other options that allows the build +system to be finely tuned. These are of the form <tt class="docutils literal"><span class="pre">name=value</span></tt> or +<tt class="docutils literal"><span class="pre">name+=value</span></tt>. The <em class="xref">--show-build-macros </em> option will display each supported <tt class="docutils literal"><span class="pre">name</span></tt>, although not +all are applicable to all platforms.</p> +<p>The <tt class="docutils literal"><span class="pre">name=value</span></tt> form means that <tt class="docutils literal"><span class="pre">value</span></tt> will replace the existing value of +<tt class="docutils literal"><span class="pre">name</span></tt>.</p> +<p>The <tt class="docutils literal"><span class="pre">name+=value</span></tt> form means that <tt class="docutils literal"><span class="pre">value</span></tt> will be appended to the existing +value of <tt class="docutils literal"><span class="pre">name</span></tt>.</p> +<p>For example, the following will disable support for C++ exceptions (and so +reduce the size of module binaries) when used with GCC:</p> +<div class="highlight-python"><pre>python configure.py CXXFLAGS+=-fno-exceptions</pre> +</div> +<p>A pure Python module called <tt class="docutils literal"><span class="pre">sipconfig.py</span></tt> is generated by <tt class="docutils literal"><span class="pre">configure.py</span></tt>. +This defines each <tt class="docutils literal"><span class="pre">name</span></tt> and its corresponding <tt class="docutils literal"><span class="pre">value</span></tt>. Looking at it will +give you a good idea of how the build system uses the different options. It is +covered in detail in <a class="reference external" href="build_system.html#ref-build-system"><em>The Build System</em></a>.</p> +<div class="section" id="configuring-for-mingw"> +<h3>Configuring for MinGW<a class="headerlink" href="#configuring-for-mingw" title="Permalink to this headline">¶</a></h3> +<p>SIP, and the modules it generates, can be built with MinGW, the Windows port of +GCC. You must use the <a class="reference internal" href="#cmdoption-configure.py-p"><em class="xref">--platform</em></a> command line +option to specify the correct platform. For example:</p> +<div class="highlight-python"><pre>c:\python26\python configure.py --platform win32-g++</pre> +</div> +</div> +<div class="section" id="configuring-for-the-borland-c-compiler"> +<h3>Configuring for the Borland C++ Compiler<a class="headerlink" href="#configuring-for-the-borland-c-compiler" title="Permalink to this headline">¶</a></h3> +<p>SIP, and the modules it generates, can be built with the free Borland C++ +compiler. You must use the <a class="reference internal" href="#cmdoption-configure.py-p"><em class="xref">--platform</em></a> command line +option to specify the correct platform. For example:</p> +<div class="highlight-python"><pre>c:\python26\python configure.py --platform win32-borland</pre> +</div> +<p>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:</p> +<div class="highlight-python"><pre>coff2omf python26.lib python26_bcpp.lib</pre> +</div> +</div> +</div> +<div class="section" id="building"> +<h2>Building<a class="headerlink" href="#building" title="Permalink to this headline">¶</a></h2> +<p>The next step is to build SIP by running your platform’s <tt class="docutils literal"><span class="pre">make</span></tt> command. For +example:</p> +<div class="highlight-python"><div class="highlight"><pre><span class="n">make</span> +</pre></div> +</div> +<p>The final step is to install SIP by running the following command:</p> +<div class="highlight-python"><pre>make install</pre> +</div> +<p>(Depending on your system you may require root or administrator privileges.)</p> +<p>This will install the various SIP components.</p> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference external" href="#">Installation</a><ul> +<li><a class="reference external" href="#downloading">Downloading</a></li> +<li><a class="reference external" href="#configuring">Configuring</a><ul> +<li><a class="reference external" href="#configuring-for-mingw">Configuring for MinGW</a></li> +<li><a class="reference external" href="#configuring-for-the-borland-c-compiler">Configuring for the Borland C++ Compiler</a></li> +</ul> +</li> +<li><a class="reference external" href="#building">Building</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="incompatibilities.html" + title="previous chapter">Potential Incompatibilities with Earlier Versions</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="using.html" + title="next chapter">Using SIP</a></p> + <div id="searchbox" style="display: none"> + <h3>Quick search</h3> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" size="18" /> + <input type="submit" value="Go" /> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </form> + <p class="searchtip" style="font-size: 90%"> + Enter search terms or a module, class or function name. + </p> + </div> + <script type="text/javascript">$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="modindex.html" title="Global Module Index" + >modules</a> |</li> + <li class="right" > + <a href="using.html" title="Using SIP" + >next</a> |</li> + <li class="right" > + <a href="incompatibilities.html" title="Potential Incompatibilities with Earlier Versions" + >previous</a> |</li> + <li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2010 Riverbank Computing Limited. + Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.4. + </div> + </body> +</html>
\ No newline at end of file diff --git a/doc/html/introduction.html b/doc/html/introduction.html new file mode 100644 index 0000000..c952bf7 --- /dev/null +++ b/doc/html/introduction.html @@ -0,0 +1,239 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + + <title>Introduction — SIP 4.10.5 Reference Guide</title> + <link rel="stylesheet" href="_static/default.css" type="text/css" /> + <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '#', + VERSION: '4.10.5', + COLLAPSE_MODINDEX: false, + FILE_SUFFIX: '.html', + HAS_SOURCE: true + }; + </script> + <script type="text/javascript" src="_static/jquery.js"></script> + <script type="text/javascript" src="_static/doctools.js"></script> + <link rel="top" title="SIP 4.10.5 Reference Guide" href="index.html" /> + <link rel="next" title="Potential Incompatibilities with Earlier Versions" href="incompatibilities.html" /> + <link rel="prev" title="SIP Reference Guide" href="index.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="modindex.html" title="Global Module Index" + accesskey="M">modules</a> |</li> + <li class="right" > + <a href="incompatibilities.html" title="Potential Incompatibilities with Earlier Versions" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="index.html" title="SIP Reference Guide" + accesskey="P">previous</a> |</li> + <li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="introduction"> +<h1>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h1> +<p>This is the reference guide for SIP 4.10.5. SIP is a tool for +automatically generating <a class="reference external" href="http://www.python.org">Python</a> bindings for C and +C++ libraries. SIP was originally developed in 1998 for +<a class="reference external" href="http://www.riverbankcomputing.com/software/pyqt">PyQt</a> - the Python +bindings for the Qt GUI toolkit - but is suitable for generating bindings for +any C or C++ library.</p> +<p>This version of SIP generates bindings for Python v2.3 or later, including +Python v3.</p> +<p>There are many other similar tools available. One of the original such tools +is <a class="reference external" href="http://www.swig.org">SWIG</a> 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.</p> +<p>The homepage for SIP is <a class="reference external" href="http://www.riverbankcomputing.com/software/sip">http://www.riverbankcomputing.com/software/sip</a>. Here +you will always find the latest stable version and the latest version of this +documentation.</p> +<p>SIP can also be downloaded from the +<a class="reference external" href="http://mercurial.selenic.com/">Mercurial</a> repository at +<a class="reference external" href="http://www.riverbankcomputing.com/hg/sip">http://www.riverbankcomputing.com/hg/sip</a>.</p> +<div class="section" id="license"> +<h2>License<a class="headerlink" href="#license" title="Permalink to this headline">¶</a></h2> +<p>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.</p> +</div> +<div class="section" id="features"> +<h2>Features<a class="headerlink" href="#features" title="Permalink to this headline">¶</a></h2> +<p>SIP, and the bindings it produces, have the following features:</p> +<ul class="simple"> +<li>bindings are fast to load and minimise memory consumption especially when +only a small sub-set of a large library is being used</li> +<li>automatic conversion between standard Python and C/C++ data types</li> +<li>overloading of functions and methods with different argument signatures</li> +<li>support for Python’s keyword argument syntax</li> +<li>support for both explicitly specified and automatically generated docstrings</li> +<li>access to a C++ class’s protected methods</li> +<li>the ability to define a Python class that is a sub-class of a C++ class, +including abstract C++ classes</li> +<li>Python sub-classes can implement the <tt class="xref docutils literal"><span class="pre">__dtor__()</span></tt> method which will be +called from the C++ class’s virtual destructor</li> +<li>support for ordinary C++ functions, class methods, static class methods, +virtual class methods and abstract class methods</li> +<li>the ability to re-implement C++ virtual and abstract methods in Python</li> +<li>support for global and class variables</li> +<li>support for global and class operators</li> +<li>support for C++ namespaces</li> +<li>support for C++ templates</li> +<li>support for C++ exceptions and wrapping them as Python exceptions</li> +<li>the automatic generation of complementary rich comparison slots</li> +<li>support for deprecation warnings</li> +<li>the ability to define mappings between C++ classes and similar Python data +types that are automatically invoked</li> +<li>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</li> +<li>the ability to change the type and meta-type of the Python object used to +wrap a C/C++ data type</li> +<li>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</li> +<li>support for consolidated modules where the generated wrapper code for a +number of related modules may be included in a single, possibly private, +module</li> +<li>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</li> +<li>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</li> +<li>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</li> +<li>the ability to include documentation in the specification files which can be +extracted and subsequently processed by external tools</li> +<li>the ability to include copyright notices and licensing information in the +specification files that is automatically included in all generated source +code</li> +<li>a build system, written in Python, that you can extend to configure, compile +and install your own bindings without worrying about platform specific issues</li> +<li>support for building your extensions using distutils</li> +<li>SIP, and the bindings it produces, runs under UNIX, Linux, Windows and +MacOS/X</li> +</ul> +</div> +<div class="section" id="sip-components"> +<h2>SIP Components<a class="headerlink" href="#sip-components" title="Permalink to this headline">¶</a></h2> +<p>SIP comprises a number of different components.</p> +<ul class="simple"> +<li>The SIP code generator (<strong>sip</strong>). This processes <tt class="docutils literal"><span class="pre">.sip</span></tt> +specification files and generates C or C++ bindings. It is covered in detail +in <a class="reference external" href="using.html#ref-using"><em>Using SIP</em></a>.</li> +<li>The SIP header file (<tt class="docutils literal"><span class="pre">sip.h</span></tt>). This contains definitions and data +structures needed by the generated C and C++ code.</li> +<li>The SIP module (<tt class="docutils literal"><span class="pre">sip.so</span></tt> or <tt class="docutils literal"><span class="pre">sip.pyd</span></tt>). This is a Python +extension module that is imported automatically by SIP generated bindings and +provides them with some common utility functions. See also +<a class="reference external" href="python_api.html#ref-python-api"><em>Python API for Applications</em></a>.</li> +<li>The SIP build system (<tt class="docutils literal"><span class="pre">sipconfig.py</span></tt>). 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 <a class="reference external" href="build_system.html#ref-build-system"><em>The Build System</em></a>.</li> +<li>The SIP distutils extension (<tt class="docutils literal"><span class="pre">sipdistutils.py</span></tt>). 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 +<a class="reference external" href="distutils.html#ref-distutils"><em>Building Your Extension with distutils</em></a>.</li> +</ul> +</div> +<div class="section" id="qt-support"> +<h2>Qt Support<a class="headerlink" href="#qt-support" title="Permalink to this headline">¶</a></h2> +<p>SIP has specific support for the creation of bindings based on Nokia’s Qt +toolkit.</p> +<p>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.</p> +<p>SIP itself does not require Qt to be installed.</p> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference external" href="#">Introduction</a><ul> +<li><a class="reference external" href="#license">License</a></li> +<li><a class="reference external" href="#features">Features</a></li> +<li><a class="reference external" href="#sip-components">SIP Components</a></li> +<li><a class="reference external" href="#qt-support">Qt Support</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="index.html" + title="previous chapter">SIP Reference Guide</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="incompatibilities.html" + title="next chapter">Potential Incompatibilities with Earlier Versions</a></p> + <div id="searchbox" style="display: none"> + <h3>Quick search</h3> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" size="18" /> + <input type="submit" value="Go" /> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </form> + <p class="searchtip" style="font-size: 90%"> + Enter search terms or a module, class or function name. + </p> + </div> + <script type="text/javascript">$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="modindex.html" title="Global Module Index" + >modules</a> |</li> + <li class="right" > + <a href="incompatibilities.html" title="Potential Incompatibilities with Earlier Versions" + >next</a> |</li> + <li class="right" > + <a href="index.html" title="SIP Reference Guide" + >previous</a> |</li> + <li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2010 Riverbank Computing Limited. + Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.4. + </div> + </body> +</html>
\ No newline at end of file diff --git a/doc/html/modindex.html b/doc/html/modindex.html new file mode 100644 index 0000000..2548832 --- /dev/null +++ b/doc/html/modindex.html @@ -0,0 +1,107 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + + <title>Global Module Index — SIP 4.10.5 Reference Guide</title> + <link rel="stylesheet" href="_static/default.css" type="text/css" /> + <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '#', + VERSION: '4.10.5', + COLLAPSE_MODINDEX: false, + FILE_SUFFIX: '.html', + HAS_SOURCE: true + }; + </script> + <script type="text/javascript" src="_static/jquery.js"></script> + <script type="text/javascript" src="_static/doctools.js"></script> + <link rel="top" title="SIP 4.10.5 Reference Guide" href="index.html" /> + + + <script type="text/javascript"> + DOCUMENTATION_OPTIONS.COLLAPSE_MODINDEX = true; + </script> + + + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="#" title="Global Module Index" + accesskey="M">modules</a> |</li> + <li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + + <h1 id="global-module-index">Global Module Index</h1> + <a href="#cap-S"><strong>S</strong></a> + <hr/> + + <table width="100%" class="indextable" cellspacing="0" cellpadding="2"><tr class="pcap"><td></td><td> </td><td></td></tr> + <tr class="cap"><td></td><td><a name="cap-S"><strong>S</strong></a></td><td></td></tr><tr> + <td></td> + <td> + <a href="python_api.html#module-sip"><tt class="xref">sip</tt></a></td><td> + <em></em></td></tr><tr> + <td></td> + <td> + <a href="build_system.html#module-sipconfig"><tt class="xref">sipconfig</tt></a></td><td> + <em></em></td></tr> + </table> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <div id="searchbox" style="display: none"> + <h3>Quick search</h3> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" size="18" /> + <input type="submit" value="Go" /> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </form> + <p class="searchtip" style="font-size: 90%"> + Enter search terms or a module, class or function name. + </p> + </div> + <script type="text/javascript">$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="#" title="Global Module Index" + >modules</a> |</li> + <li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2010 Riverbank Computing Limited. + Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.4. + </div> + </body> +</html>
\ No newline at end of file diff --git a/doc/html/objects.inv b/doc/html/objects.inv new file mode 100644 index 0000000..c3c7a2d --- /dev/null +++ b/doc/html/objects.inv @@ -0,0 +1,214 @@ +# Sphinx inventory version 1 +# Project: SIP +# Version: 4.10.5 +sipconfig mod build_system.html +sip mod python_api.html +sipGetState cfunction c_api.html +sipconfig.Makefile.optional_list method build_system.html +sip.unwrapinstance function python_api.html +SIP_VERSION cmacro c_api.html +sipCanConvertToInstance cfunction c_api.html +sipconfig.Makefile.__init__ method build_system.html +sipconfig.Makefile.optional_string method build_system.html +sipconfig.ProgramMakefile.__init__ method build_system.html +sip.voidptr.__hex__ method python_api.html +sipconfig.PythonModuleMakefile.__init__ method build_system.html +sipconfig.Makefile.extra_libs attribute build_system.html +sipconfig.Configuration.py_lib_dir attribute build_system.html +sip.isdeleted function python_api.html +sipFindMappedType cfunction c_api.html +SIP_API_MAJOR_NR cmacro c_api.html +sipLong_AsUnsignedLong cfunction c_api.html +sipTransferTo cfunction c_api.html +sipConvertFromEnum cfunction c_api.html +sipconfig.create_wrapper function build_system.html +sipconfig.Configuration.py_inc_dir attribute build_system.html +sipIntTypeClassMap ctype c_api.html +dd_name cmember annotations.html +sipconfig.ProgramMakefile.generate_target_default method build_system.html +sipconfig.SIPModuleMakefile class build_system.html +sipconfig.Configuration.default_bin_dir attribute build_system.html +sipconfig.ProgramMakefile.build_command method build_system.html +sipconfig.ModuleMakefile.generate_target_install method build_system.html +sipconfig.Configuration.build_macros method build_system.html +sipconfig.Configuration.__init__ method build_system.html +sipconfig.Makefile.generate method build_system.html +sipReleaseType cfunction c_api.html +sip.transferback function python_api.html +sip.voidptr.asstring method python_api.html +SIP_NO_CONVERTORS cmacro c_api.html +sipconfig.Makefile.install_file method build_system.html +sipResolveTypedef cfunction c_api.html +sipTypeName cfunction c_api.html +sipConvertToInstance cfunction c_api.html +sip.voidptr.__int__ method python_api.html +sipconfig.Makefile.finalise method build_system.html +sipconfig.format function build_system.html +sipMapIntToClass cfunction c_api.html +sipconfig.SIPModuleMakefile.finalise method build_system.html +sipconfig.Makefile.config attribute build_system.html +sipFindType cfunction c_api.html +sipconfig.Configuration.py_conf_inc_dir attribute build_system.html +sipWrapperType ctype c_api.html +sipConvertFromType cfunction c_api.html +sipconfig.inform function build_system.html +sipconfig.Makefile.extra_cflags attribute build_system.html +sipconfig.ProgramMakefile.generate_macros_and_rules method build_system.html +sipTypeIsEnum cfunction c_api.html +sipconfig.ParentMakefile.generate_target_default method build_system.html +sipSimpleWrapper_Type cvar c_api.html +sipconfig.ModuleMakefile.generate_target_clean method build_system.html +sipconfig.ParentMakefile class build_system.html +sipForceConvertToMappedType cfunction c_api.html +sipconfig.Makefile.rm attribute build_system.html +sipconfig.Makefile.generator attribute build_system.html +sipTypeIsNamespace cfunction c_api.html +sipconfig.Makefile.generate_target_default method build_system.html +sipCanConvertToType cfunction c_api.html +sipconfig.Configuration.universal attribute build_system.html +sipConvertFromConstVoidPtrAndSize cfunction c_api.html +sipconfig.Makefile.platform_lib method build_system.html +typeString cmember c_api.html +sip.voidptr.__init__ method python_api.html +sipTypeIsMapped cfunction c_api.html +sipconfig.Configuration.set_build_macros method build_system.html +sipconfig.Makefile.mkdir attribute build_system.html +sipForceConvertToType cfunction c_api.html +sipconfig.ParentMakefile.generate_macros_and_rules method build_system.html +dd_next cmember annotations.html +sip.voidptr.ascapsule method python_api.html +sip.SIP_VERSION_STR data python_api.html +sipExportSymbol cfunction c_api.html +sipconfig.Configuration.sip_version_str attribute build_system.html +sipconfig.version_to_sip_tag function build_system.html +sipconfig.PythonModuleMakefile.generate_macros_and_rules method build_system.html +sipconfig.Makefile.extra_lflags attribute build_system.html +sipBadLengthForSlice cfunction c_api.html +sipConvertToMappedType cfunction c_api.html +sipconfig.version_to_string function build_system.html +sipconfig.ProgramMakefile.generate_target_clean method build_system.html +sipTypeAsPyTypeObject cfunction c_api.html +sipIsAPIEnabled cfunction c_api.html +sipconfig.Makefile.extra_lib_dirs attribute build_system.html +dd_ptr cmember annotations.html +sipconfig.PythonModuleMakefile class build_system.html +sipconfig.error function build_system.html +sip.voidptr.getwriteable method python_api.html +sipconfig.Makefile.generate_target_clean method build_system.html +sipForceConvertToInstance cfunction c_api.html +sipConvertFromVoidPtrAndSize cfunction c_api.html +sipconfig.Makefile.extra_cxxflags attribute build_system.html +sip.wrapinstance function python_api.html +sip.voidptr.getsize method python_api.html +sipconfig.ProgramMakefile class build_system.html +sip.wrappertype class python_api.html +sipReleaseMappedType cfunction c_api.html +sipStringTypeClassMap ctype c_api.html +sipconfig.Makefile.extra_defines attribute build_system.html +SIP_API_MINOR_NR cmacro c_api.html +sipconfig.Configuration class build_system.html +sipconfig.Makefile.generate_macros_and_rules method build_system.html +sipFree cfunction c_api.html +sip.voidptr.ascobject method python_api.html +sipVoidPtr_Type cvar c_api.html +sipconfig.ParentMakefile.__init__ method build_system.html +sipconfig.Makefile.ready method build_system.html +sipconfig.Makefile.required_string method build_system.html +sipRegisterAttributeGetter cfunction c_api.html +sip.ispyowned function python_api.html +sipconfig.ParentMakefile.generate_target_install method build_system.html +sipSimpleWrapper ctype c_api.html +sipconfig.Configuration.default_mod_dir attribute build_system.html +SIP_NOT_NONE cmacro c_api.html +sipConvertFromNewType cfunction c_api.html +sipTypeFromPyTypeObject cfunction c_api.html +SIP_PROTECTED_IS_PUBLIC cmacro c_api.html +sipconfig.ModuleMakefile.__init__ method build_system.html +sipconfig.Configuration.sip_bin attribute build_system.html +SIP_VERSION_STR cmacro c_api.html +sipConvertToType cfunction c_api.html +sipconfig.Makefile.generate_target_install method build_system.html +sipClassName cfunction c_api.html +sip.voidptr.setsize method python_api.html +sipDelayedDtor ctype annotations.html +sipconfig.SIPModuleMakefile.__init__ method build_system.html +sipconfig.Configuration.sip_inc_dir attribute build_system.html +sipconfig.parse_build_macros function build_system.html +sipConvertFromInstance cfunction c_api.html +sipconfig.Configuration.py_version attribute build_system.html +sipWrapperType_Type cvar c_api.html +sipConvertFromNewInstance cfunction c_api.html +sipTransferBack cfunction c_api.html +sipconfig.Configuration.default_sip_dir attribute build_system.html +sipConvertFromMappedType cfunction c_api.html +sipconfig.Configuration.sip_version attribute build_system.html +sipWrapper_Type cvar c_api.html +sipconfig.ModuleMakefile.finalise method build_system.html +sipconfig.Configuration.sip_config_args attribute build_system.html +dd_isderived cmember annotations.html +sipconfig.read_version function build_system.html +sipConvertFromConstVoidPtr cfunction c_api.html +sipTypeIsClass cfunction c_api.html +sipBadCatcherResult cfunction c_api.html +sip.delete function python_api.html +sipGetPyObject cfunction c_api.html +sipconfig.Makefile class build_system.html +SIP_UNBLOCK_THREADS cmacro c_api.html +sipReleaseInstance cfunction c_api.html +sip.transferto function python_api.html +sip.voidptr.setwriteable method python_api.html +sipconfig.ProgramMakefile.generate_target_install method build_system.html +sipconfig.create_config_module function build_system.html +sipWrapper_Check cfunction c_api.html +sipConvertFromSequenceIndex cfunction c_api.html +sipTransferBreak cfunction c_api.html +typeInt cmember c_api.html +sipMapStringToClass cfunction c_api.html +sipConvertFromSliceObject cfunction c_api.html +sipTypeScope cfunction c_api.html +sipImportSymbol cfunction c_api.html +sipconfig.Configuration.platform attribute build_system.html +sipconfig.ModuleMakefile.module_as_lib method build_system.html +sipconfig.PythonModuleMakefile.generate_target_install method build_system.html +sip.getapi function python_api.html +sip.cast function python_api.html +sip.voidptr class python_api.html +sipconfig.Makefile.chkdir attribute build_system.html +sipDelayedDtors cfunction annotations.html +sipRegisterPyType cfunction c_api.html +sipconfig.Makefile.clean_build_file_objects method build_system.html +sipconfig.Makefile.parse_build_file method build_system.html +sipconfig.create_content function build_system.html +sipConvertFromNamedEnum cfunction c_api.html +SIP_BLOCK_THREADS cmacro c_api.html +sipconfig.Makefile.copy attribute build_system.html +sip.setdeleted function python_api.html +sip.setapi function python_api.html +sipconfig.ParentMakefile.generate_target_clean method build_system.html +sipconfig.Makefile.extra_include_dirs attribute build_system.html +sipGetWrapper cfunction c_api.html +sipconfig.ModuleMakefile.generate_target_default method build_system.html +sipconfig.ProgramMakefile.finalise method build_system.html +sipBadCallableArg cfunction c_api.html +sipMalloc cfunction c_api.html +sipFindNamedEnum cfunction c_api.html +user cmember c_api.html +sipCanConvertToEnum cfunction c_api.html +sipconfig.Makefile.console attribute build_system.html +sipCanConvertToMappedType cfunction c_api.html +sipWrapper ctype c_api.html +sip.wrapper class python_api.html +sipCallMethod cfunction c_api.html +sipconfig.Configuration.arch attribute build_system.html +sip.SIP_VERSION data python_api.html +sipParseResult cfunction c_api.html +sipBuildResult cfunction c_api.html +sip.settracemask function python_api.html +sipFindClass cfunction c_api.html +sipconfig.ModuleMakefile class build_system.html +sipconfig.ModuleMakefile.generate_macros_and_rules method build_system.html +sipconfig.Configuration.sip_mod_dir attribute build_system.html +sipConvertToVoidPtr cfunction c_api.html +sip.dump function python_api.html +SIP_SSIZE_T cmacro c_api.html +sipConvertFromVoidPtr cfunction c_api.html diff --git a/doc/html/python_api.html b/doc/html/python_api.html new file mode 100644 index 0000000..633ac2a --- /dev/null +++ b/doc/html/python_api.html @@ -0,0 +1,528 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + + <title>Python API for Applications — SIP 4.10.5 Reference Guide</title> + <link rel="stylesheet" href="_static/default.css" type="text/css" /> + <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '#', + VERSION: '4.10.5', + COLLAPSE_MODINDEX: false, + FILE_SUFFIX: '.html', + HAS_SOURCE: true + }; + </script> + <script type="text/javascript" src="_static/jquery.js"></script> + <script type="text/javascript" src="_static/doctools.js"></script> + <link rel="top" title="SIP 4.10.5 Reference Guide" href="index.html" /> + <link rel="next" title="The Build System" href="build_system.html" /> + <link rel="prev" title="Using the C API when Embedding" href="embedding.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="modindex.html" title="Global Module Index" + accesskey="M">modules</a> |</li> + <li class="right" > + <a href="build_system.html" title="The Build System" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="embedding.html" title="Using the C API when Embedding" + accesskey="P">previous</a> |</li> + <li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="module-sip"> +<span id="ref-python-api"></span><h1>Python API for Applications<a class="headerlink" href="#module-sip" title="Permalink to this headline">¶</a></h1> +<p>The main purpose of the <tt class="xref docutils literal"><span class="pre">sip</span></tt> 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.</p> +<dl class="function"> +<dt id="sip.cast"> +<tt class="descclassname">sip.</tt><tt class="descname">cast</tt><big>(</big><em>obj</em>, <em>type</em><big>)</big> → object<a class="headerlink" href="#sip.cast" title="Permalink to this definition">¶</a></dt> +<dd><p>This does the Python equivalent of casting a C++ instance to one of its +sub or super-class types.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><em>obj</em> – the Python object.</li> +<li><em>type</em> – the type.</li> +</ul> +</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">a new Python object is that wraps the same C++ instance as <em>obj</em>, but +has the type <em>type</em>.</p> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="sip.delete"> +<tt class="descclassname">sip.</tt><tt class="descname">delete</tt><big>(</big><em>obj</em><big>)</big><a class="headerlink" href="#sip.delete" title="Permalink to this definition">¶</a></dt> +<dd><p>For C++ instances this calls the C++ destructor. For C structures it +returns the structure’s memory to the heap.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>obj</em> – the Python object.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="sip.dump"> +<tt class="descclassname">sip.</tt><tt class="descname">dump</tt><big>(</big><em>obj</em><big>)</big><a class="headerlink" href="#sip.dump" title="Permalink to this definition">¶</a></dt> +<dd><p>This displays various bits of useful information about the internal state +of the Python object that wraps a C++ instance or C structure.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>obj</em> – the Python object.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="sip.getapi"> +<tt class="descclassname">sip.</tt><tt class="descname">getapi</tt><big>(</big><em>name</em><big>)</big> → version<a class="headerlink" href="#sip.getapi" title="Permalink to this definition">¶</a></dt> +<dd><p> +<span class="versionmodified">New in version 4.9.</span></p> +<p>This returns the version number that has been set for an API. The version +number is either set explicitly by a call to <a title="sip.setapi" class="reference internal" href="#sip.setapi"><tt class="xref docutils literal"><span class="pre">sip.setapi()</span></tt></a> or +implicitly by importing the module that defines it.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>name</em> – the name of the API.</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body">The version number that has been set for the API. An exception will +be raised if the API is unknown.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="sip.isdeleted"> +<tt class="descclassname">sip.</tt><tt class="descname">isdeleted</tt><big>(</big><em>obj</em><big>)</big> → bool<a class="headerlink" href="#sip.isdeleted" title="Permalink to this definition">¶</a></dt> +<dd><p>This checks if the C++ instance or C structure has been deleted and +returned to the heap.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>obj</em> – the Python object.</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="xref docutils literal"><span class="pre">True</span></tt> if the C/C++ instance has been deleted.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="sip.ispyowned"> +<tt class="descclassname">sip.</tt><tt class="descname">ispyowned</tt><big>(</big><em>obj</em><big>)</big> → bool<a class="headerlink" href="#sip.ispyowned" title="Permalink to this definition">¶</a></dt> +<dd><p>This checks if the C++ instance or C structure is owned by Python.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>obj</em> – the Python object.</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="xref docutils literal"><span class="pre">True</span></tt> if the C/C++ instance is owned by Python.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="sip.setapi"> +<tt class="descclassname">sip.</tt><tt class="descname">setapi</tt><big>(</big><em>name</em>, <em>version</em><big>)</big><a class="headerlink" href="#sip.setapi" title="Permalink to this definition">¶</a></dt> +<dd><p> +<span class="versionmodified">New in version 4.9.</span></p> +<p>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.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><em>name</em> – the name of the API.</li> +<li><em>version</em> – The version number to set for the API. Version numbers must be +greater than or equal to 1.</li> +</ul> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="sip.setdeleted"> +<tt class="descclassname">sip.</tt><tt class="descname">setdeleted</tt><big>(</big><em>obj</em><big>)</big><a class="headerlink" href="#sip.setdeleted" title="Permalink to this definition">¶</a></dt> +<dd><p>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.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>obj</em> – the Python object.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="function"> +<dt id="sip.settracemask"> +<tt class="descclassname">sip.</tt><tt class="descname">settracemask</tt><big>(</big><em>mask</em><big>)</big><a class="headerlink" href="#sip.settracemask" title="Permalink to this definition">¶</a></dt> +<dd><p>If the bindings have been created with SIP’s <a class="reference external" href="command_line.html#cmdoption-sip-r"><em class="xref">-r</em></a> 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.)</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>mask</em> – the mask that determines which debugging statements are enabled.</td> +</tr> +</tbody> +</table> +<p>Debugging statements are generated at the following points:</p> +<ul class="simple"> +<li>in a C++ virtual function (<em>mask</em> is <tt class="docutils literal"><span class="pre">0x0001</span></tt>)</li> +<li>in a C++ constructor (<em>mask</em> is <tt class="docutils literal"><span class="pre">0x0002</span></tt>)</li> +<li>in a C++ destructor (<em>mask</em> is <tt class="docutils literal"><span class="pre">0x0004</span></tt>)</li> +<li>in a Python type’s __init__ method (<em>mask</em> is <tt class="docutils literal"><span class="pre">0x0008</span></tt>)</li> +<li>in a Python type’s __del__ method (<em>mask</em> is <tt class="docutils literal"><span class="pre">0x0010</span></tt>)</li> +<li>in a Python type’s ordinary method (<em>mask</em> is <tt class="docutils literal"><span class="pre">0x0020</span></tt>).</li> +</ul> +<p>By default the trace mask is zero and all debugging statements are +disabled.</p> +</dd></dl> + +<dl class="data"> +<dt id="sip.SIP_VERSION"> +<tt class="descclassname">sip.</tt><tt class="descname">SIP_VERSION</tt><a class="headerlink" href="#sip.SIP_VERSION" title="Permalink to this definition">¶</a></dt> +<dd>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 <tt class="docutils literal"><span class="pre">0x040000</span></tt>). +It was first implemented in SIP v4.2.</dd></dl> + +<dl class="data"> +<dt id="sip.SIP_VERSION_STR"> +<tt class="descclassname">sip.</tt><tt class="descname">SIP_VERSION_STR</tt><a class="headerlink" href="#sip.SIP_VERSION_STR" title="Permalink to this definition">¶</a></dt> +<dd>This is a Python string object that defines the SIP version number as +represented as a string. For development snapshots it will start with +<tt class="docutils literal"><span class="pre">snapshot-</span></tt>. It was first implemented in SIP v4.3.</dd></dl> + +<dl class="function"> +<dt id="sip.transferback"> +<tt class="descclassname">sip.</tt><tt class="descname">transferback</tt><big>(</big><em>obj</em><big>)</big><a class="headerlink" href="#sip.transferback" title="Permalink to this definition">¶</a></dt> +<dd>This function is a wrapper around <a title="sipTransferBack" class="reference external" href="c_api.html#sipTransferBack"><tt class="xref docutils literal"><span class="pre">sipTransferBack()</span></tt></a>.</dd></dl> + +<dl class="function"> +<dt id="sip.transferto"> +<tt class="descclassname">sip.</tt><tt class="descname">transferto</tt><big>(</big><em>obj</em>, <em>owner</em><big>)</big><a class="headerlink" href="#sip.transferto" title="Permalink to this definition">¶</a></dt> +<dd>This function is a wrapper around <a title="sipTransferTo" class="reference external" href="c_api.html#sipTransferTo"><tt class="xref docutils literal"><span class="pre">sipTransferTo()</span></tt></a>.</dd></dl> + +<dl class="function"> +<dt id="sip.unwrapinstance"> +<tt class="descclassname">sip.</tt><tt class="descname">unwrapinstance</tt><big>(</big><em>obj</em><big>)</big> → integer<a class="headerlink" href="#sip.unwrapinstance" title="Permalink to this definition">¶</a></dt> +<dd><p>This returns the address, as an integer, of a wrapped C/C++ structure or +class instance.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>obj</em> – the Python object.</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body">an integer that is the address of the C/C++ instance.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="class"> +<dt id="sip.voidptr"> +<em class="property">class </em><tt class="descclassname">sip.</tt><tt class="descname">voidptr</tt><a class="headerlink" href="#sip.voidptr" title="Permalink to this definition">¶</a></dt> +<dd><p>This is the type object for the type SIP uses to represent a C/C++ +<tt class="docutils literal"><span class="pre">void</span> <span class="pre">*</span></tt>. 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 <tt class="docutils literal"><span class="pre">buffer()</span></tt> +builtin. The type has the following methods.</p> +<dl class="method"> +<dt id="sip.voidptr.__init__"> +<tt class="descname">__init__</tt><big>(</big><em>address</em><span class="optional">[</span>, <em>size=-1</em><span class="optional">[</span>, <em>writeable=True</em><span class="optional">]</span><span class="optional">]</span><big>)</big><a class="headerlink" href="#sip.voidptr.__init__" title="Permalink to this definition">¶</a></dt> +<dd><table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> +<li><em>address</em> – the address, either another <a title="sip.voidptr" class="reference internal" href="#sip.voidptr"><tt class="xref docutils literal"><span class="pre">sip.voidptr</span></tt></a>, <tt class="xref docutils literal"><span class="pre">None</span></tt>, a +Python Capsule, a Python CObject, or an integer.</li> +<li><em>size</em> – the optional associated size of the block of memory and is negative +if the size is not known.</li> +<li><em>writeable</em> – set if the memory is writeable. If it is not specified, and +<em>address</em> is a <a title="sip.voidptr" class="reference internal" href="#sip.voidptr"><tt class="xref docutils literal"><span class="pre">sip.voidptr</span></tt></a> instance then its value will be +used.</li> +</ul> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="sip.voidptr.__int__"> +<tt class="descname">__int__</tt><big>(</big><big>)</big> → integer<a class="headerlink" href="#sip.voidptr.__int__" title="Permalink to this definition">¶</a></dt> +<dd><p>This returns the address as an integer.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body">the integer address.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="sip.voidptr.__hex__"> +<tt class="descname">__hex__</tt><big>(</big><big>)</big> → string<a class="headerlink" href="#sip.voidptr.__hex__" title="Permalink to this definition">¶</a></dt> +<dd><p>This returns the address as a hexadecimal string.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body">the hexadecimal string address.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="sip.voidptr.ascapsule"> +<tt class="descname">ascapsule</tt><big>(</big><big>)</big> → capsule<a class="headerlink" href="#sip.voidptr.ascapsule" title="Permalink to this definition">¶</a></dt> +<dd><p> +<span class="versionmodified">New in version 4.10.</span></p> +<p>This returns the address as an unnamed Python Capsule. This requires +Python v3.1 or later or Python v2.7 or later.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body">the Capsule.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="sip.voidptr.ascobject"> +<tt class="descname">ascobject</tt><big>(</big><big>)</big> → cObject<a class="headerlink" href="#sip.voidptr.ascobject" title="Permalink to this definition">¶</a></dt> +<dd><p>This returns the address as a Python CObject. This is deprecated with +Python v3.1 or later.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body">the CObject.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="sip.voidptr.asstring"> +<tt class="descname">asstring</tt><big>(</big><span class="optional">[</span><em>size=-1</em><span class="optional">]</span><big>)</big> → string/bytes<a class="headerlink" href="#sip.voidptr.asstring" title="Permalink to this definition">¶</a></dt> +<dd><p>This returns a copy of the block of memory as a Python v2 string object +or a Python v3 bytes object.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>size</em> – 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.</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body">the string or bytes object.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="sip.voidptr.getsize"> +<tt class="descname">getsize</tt><big>(</big><big>)</big> → integer<a class="headerlink" href="#sip.voidptr.getsize" title="Permalink to this definition">¶</a></dt> +<dd><p>This returns the size associated with the address.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body">the associated size which will be negative if there is none.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="sip.voidptr.setsize"> +<tt class="descname">setsize</tt><big>(</big><em>size</em><big>)</big><a class="headerlink" href="#sip.voidptr.setsize" title="Permalink to this definition">¶</a></dt> +<dd><p>This sets the size associated with the address.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>size</em> – the size to associate. If it is negative then no size is +associated.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="sip.voidptr.getwriteable"> +<tt class="descname">getwriteable</tt><big>(</big><big>)</big> → bool<a class="headerlink" href="#sip.voidptr.getwriteable" title="Permalink to this definition">¶</a></dt> +<dd><p>This returns the writeable state of the memory.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="xref docutils literal"><span class="pre">True</span></tt> if the memory is writeable.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="method"> +<dt id="sip.voidptr.setwriteable"> +<tt class="descname">setwriteable</tt><big>(</big><em>writeable</em><big>)</big><a class="headerlink" href="#sip.voidptr.setwriteable" title="Permalink to this definition">¶</a></dt> +<dd><p>This sets the writeable state of the memory.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>writeable</em> – the writeable state to set.</td> +</tr> +</tbody> +</table> +</dd></dl> + +</dd></dl> + +<dl class="function"> +<dt id="sip.wrapinstance"> +<tt class="descclassname">sip.</tt><tt class="descname">wrapinstance</tt><big>(</big><em>addr</em>, <em>type</em><big>)</big> → object<a class="headerlink" href="#sip.wrapinstance" title="Permalink to this definition">¶</a></dt> +<dd><p>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.</p> +<table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> +<li><em>addr</em> – the address of the instance as a number.</li> +<li><em>type</em> – the Python type of the instance.</li> +</ul> +</td> +</tr> +<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the Python object that wraps the instance.</p> +</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="class"> +<dt id="sip.wrapper"> +<em class="property">class </em><tt class="descclassname">sip.</tt><tt class="descname">wrapper</tt><a class="headerlink" href="#sip.wrapper" title="Permalink to this definition">¶</a></dt> +<dd>This is the type object of the base type of all instances wrapped by SIP.</dd></dl> + +<dl class="class"> +<dt id="sip.wrappertype"> +<em class="property">class </em><tt class="descclassname">sip.</tt><tt class="descname">wrappertype</tt><a class="headerlink" href="#sip.wrappertype" title="Permalink to this definition">¶</a></dt> +<dd>This is the type object of the metatype of the <a title="sip.wrapper" class="reference internal" href="#sip.wrapper"><tt class="xref docutils literal"><span class="pre">sip.wrapper</span></tt></a> type.</dd></dl> + +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h4>Previous topic</h4> + <p class="topless"><a href="embedding.html" + title="previous chapter">Using the C API when Embedding</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="build_system.html" + title="next chapter">The Build System</a></p> + <div id="searchbox" style="display: none"> + <h3>Quick search</h3> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" size="18" /> + <input type="submit" value="Go" /> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </form> + <p class="searchtip" style="font-size: 90%"> + Enter search terms or a module, class or function name. + </p> + </div> + <script type="text/javascript">$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="modindex.html" title="Global Module Index" + >modules</a> |</li> + <li class="right" > + <a href="build_system.html" title="The Build System" + >next</a> |</li> + <li class="right" > + <a href="embedding.html" title="Using the C API when Embedding" + >previous</a> |</li> + <li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2010 Riverbank Computing Limited. + Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.4. + </div> + </body> +</html>
\ No newline at end of file diff --git a/doc/html/search.html b/doc/html/search.html new file mode 100644 index 0000000..143be9c --- /dev/null +++ b/doc/html/search.html @@ -0,0 +1,97 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + + <title>Search — SIP 4.10.5 Reference Guide</title> + <link rel="stylesheet" href="_static/default.css" type="text/css" /> + <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '#', + VERSION: '4.10.5', + COLLAPSE_MODINDEX: false, + FILE_SUFFIX: '.html', + HAS_SOURCE: true + }; + </script> + <script type="text/javascript" src="_static/jquery.js"></script> + <script type="text/javascript" src="_static/doctools.js"></script> + <script type="text/javascript" src="_static/searchtools.js"></script> + <link rel="top" title="SIP 4.10.5 Reference Guide" href="index.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="modindex.html" title="Global Module Index" + accesskey="M">modules</a> |</li> + <li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <h1 id="search-documentation">Search</h1> + <div id="fallback" class="admonition warning"> + <script type="text/javascript">$('#fallback').hide();</script> + <p> + Please activate JavaScript to enable the search + functionality. + </p> + </div> + <p> + From here you can search these documents. Enter your search + words into the box below and click "search". Note that the search + function will automatically search for all of the words. Pages + containing fewer words won't appear in the result list. + </p> + <form action="" method="get"> + <input type="text" name="q" value="" /> + <input type="submit" value="search" /> + <span id="search-progress" style="padding-left: 10px"></span> + </form> + + <div id="search-results"> + + </div> + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="modindex.html" title="Global Module Index" + >modules</a> |</li> + <li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li> + </ul> + </div> + + <div class="footer"> + © Copyright 2010 Riverbank Computing Limited. + Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.4. + </div> + <script type="text/javascript" src="searchindex.js"></script> + + </body> +</html>
\ No newline at end of file diff --git a/doc/html/searchindex.js b/doc/html/searchindex.js new file mode 100644 index 0000000..2099b9d --- /dev/null +++ b/doc/html/searchindex.js @@ -0,0 +1 @@ +Search.setIndex({desctypes:{"0":"cfunction","1":"method","2":"function","3":"cmacro","4":"attribute","5":"ctype","6":"cmember","7":"class","8":"cvar","9":"data"},terms:{sipcanconverttoinst:[9,4],sipconvertfromtyp:[10,4],secondli:13,prefix:[0,13,10,11,4],mkcustom:7,whose:[13,8,4],accur:12,"const":[4,10,11,12,13,8],cmdclass:3,pylist_set_item:10,under:[0,5,10,2],qlabel:13,everi:[0,13],ascapsul:14,"void":[4,14,10,12,13,8],affect:[0,10],"__nonzero__":12,factori:[13,8,4],sip_pydict:[12,8],initialis:[0,13,10],sipconvertfromvoidptrands:4,abil:[0,5],direct:[0,1,4,6,10,12,13,8],second:0,b_mod:10,module_as_lib:0,even:[12,9,10],neg:[0,14,4],qpoint:10,"new":[3,4,5,8,10,12,13,14],net:0,ever:8,sipdisconnectrx:9,getsiz:14,q_os_win:13,mem:4,never:[13,10,8,4],here:[5,12],debugg:8,path:[13,2,3],interpret:[0,1,2,4,5,6,7,10,11,12,13,8],incdir:2,adopt:10,create_cont:0,create_word:13,sip_derived_class:10,mkdir:0,default_sip_dir:[0,13],unix:[0,5,7,13],pythonmodulemakefil:0,total:10,unit:10,describ:[3,4,5,6,7,9,10,12,13,8],would:[13,7,10,8,4],sipregisterattributegett:[13,4],call:[0,2,4,5,6,7,8,9,10,11,12,13,14],python26:2,type:[1,4,5,8,9,10,11,12,13,14],until:[13,8],autogen:8,successful:4,relat:[5,10,2,13],notic:5,warn:[0,5,6,8],"__iter__":12,sipimportsymbol:4,must:[0,2,4,5,6,7,8,9,10,11,12,13,14],join:13,restor:4,arbitari:10,setup:3,work:[0,4,9,10,13,8],sipbadcallablearg:4,root:[10,2],could:[0,13,10],overrid:[0,13,10],give:[13,2],indic:[0,10],want:[0,13,7,8,3],sip_module_dict:11,slicelen:4,unsign:[12,8,4],end:[12,13,10,4],quot:8,ordinari:[5,13,14],how:[2,5,7,10,11,13],answer:13,place:[0,4,6,10,13,8],coff2omf:2,config:[0,13,3],bindir:2,updat:[8,4],after:[0,2,4,10,13,8],sipwrapp:[9,4],"_pkg_config":13,py_buff:10,befor:[0,4,6,10,13,8],wrong:12,nokeywordarg:8,arch:[0,2],parallel:6,demonstr:13,attempt:[10,4],opaqu:[12,4],c_mod:10,exclud:[0,10,8],maintain:[0,13],finalis:[0,13],exclus:[13,10],get_sip_api:11,order:[13,10,8,4],origin:[5,10,8],composit:10,over:[0,10],becaus:[5,13,7,10],privileg:2,keyboard:12,pyerr_setstr:10,delaydtor:8,easier:[0,13,6,4],this_word:13,thei:[0,7,9,10,12,13,8],fragment:[10,11],safe:[5,9,10,4],"break":[13,10],singleshot:8,choic:[5,13,10],bigetreadbuffercod:[12,10],unpickl:10,each:[0,2,4,6,7,10,11,13,8],debug:[0,6,10,2,14],bigetsegcountcod:[12,10],side:10,mean:[0,2,8,9,10,13,14],v1_0:10,v1_1:10,sipcanconverttomappedtyp:[9,4],sipemitslot:9,collector:[13,10,8,4],unbound:8,sip_nameerror:12,goe:5,newli:[13,9,8,4],pycobject:[11,4],content:[0,3,4,10,13,8],pyqtconfig:[0,13],allownon:8,build_fil:[0,13],situat:13,free:[13,2],standard:[2,3,5,7,10,13],"__setitem__":[12,8,4],voidptr:[8,14,4],precompil:10,foo_support:10,extra_cflag:0,v3_0:10,isn:[10,14,4],setwrit:14,"__or__":12,rang:[13,10,8,4],siperr:10,python26_bcpp:2,independ:10,restrict:[7,10,8],hook:3,unlik:[5,13,10],mingw:[0,2],messag:[0,6,2],wasn:4,sip_keyerror:12,iserr:4,top:[0,13],sometim:[12,13,7,8],fiction:13,mercuri:5,too:10,consol:[0,7],namespac:[5,12,10,4],tool:5,lower:[10,8,11,4],sipcanconverttotyp:[10,4],read_vers:0,reinterpret_cast:10,target:0,keyword:[5,10,6,8,13],provid:[0,4,5,6,8,7,10,12,13,14],zero:[0,4,8,7,10,13,14],sipexceptionref:10,matter:[12,13,10],wchar_t:[12,13,4],sip_lookuperror:12,modern:6,increment:[10,4],incompat:[1,4,9,10,13,8],sipwrappertyp:[10,4],pydict_getitemstr:11,simplifi:10,though:9,sipself:10,object:[0,1,4,5,8,9,10,11,12,13,14],lexic:4,letter:4,don:10,doc:[12,10,6],doe:[0,4,5,7,8,9,12,13,14],declar:[4,6,10,12,13,8],unchang:[10,4],dot:[12,10,8],"__str__":12,syntax:[1,5,6,12,13,8],qstring:[13,10],identifi:[10,8,4],siperror:[10,4],involv:4,absolut:0,pystring_fromstr:4,acquir:[13,10,4],configur:[0,1,2,5,7,9,13],sip_build:9,dd_name:8,qwidget:[13,10,8],"__call__":12,stop:4,report:10,bar:13,emb:11,baz:13,method:[0,4,5,6,7,8,9,10,12,13,14],sipclass:10,pyexc_valueerror:10,set_build_macro:0,result:[10,6,8,4],respons:[5,13,9,10,4],fail:[10,4],subject:13,sip_unicodetranslateerror:12,hopefulli:13,simplest:13,sip_zerodivisionerror:12,clean_build_file_object:0,handwritten:[1,4,9,10,11,12,8],accord:[13,7,4],extend:[5,13,10],sip_overflowerror:12,extens:[0,1,3,4,5,13],lazi:[1,13,4],preprocessor:[0,13,9,10,4],rtti:[10,4],protect:[0,4,5,6,7,10,12,13],expos:14,howev:[2,8,10,11,12,13,14],against:[0,13,10],sipfindclass:[9,4],logic:10,fno:2,com:[5,2],create_wrapp:0,seqlen:4,getwrit:14,setapi:[13,14],guid:[5,1],assum:[0,13,2,8,4],three:[0,13],been:[0,2,4,8,9,10,11,12,13,14],much:13,siptypeismap:4,interest:13,q_signal:12,"__len__":[12,8],sipconvertfrominst:[9,4],life:13,suppress:[8,4],argument:[0,1,4,5,6,7,9,10,12,13,8],child:13,"catch":[10,6],riverbankcomput:[5,2],wobj:10,qtcoremod:[13,10],ident:10,visitproc:10,properti:0,weren:9,"__ge__":12,have:[0,2,4,5,7,8,9,10,11,12,13,14],sip_slot_con:12,tabl:4,toolkit:5,sever:[5,4],sipselfwasarg:10,docvalu:8,receiv:12,suggest:13,make:[0,2,4,5,6,7,9,10,12,13,8],export_al:0,bigetbuffercod:[12,10],complex:[1,13],split:[13,6],sipgetsend:9,complet:[10,6,14],sip_api_major_nr:4,"__idiv__":12,rais:[0,13,10,14,4],ownership:[1,4,5,10,13,8],qaccel:12,tune:[0,13,2],redefin:[0,10,6,4],kept:[8,4],siptypeisclass:4,inherit:13,sip_importerror:12,thi:[0,2,4,5,6,7,8,9,10,12,13,14],endif:[13,10],programm:[12,10],everyth:13,left:[0,10,8],sip_keyboardinterrupt:12,protocol:[8,14,4],just:[0,3,4,9,10,13],gctraversecod:[12,10],previous:[9,4],easi:0,had:[5,9],sip_eoferror:12,qtguimod:[13,10],siptypeaspytypeobject:4,els:[13,10],save:4,opt:3,applic:[1,2,4,5,7,10,11,13,14],wai:[13,7,10,4],specif:[0,1,2,4,5,6,9,10,12,13,8],arbitrari:10,"__long__":12,sip_syntaxerror:12,cxxflag:2,underli:[12,8],www:[5,2],pymem_malloc:4,old:[13,9],deal:[12,13,10],sip_indentationerror:12,intern:[12,10,14],indirect:10,successfulli:[10,8],"__iand__":12,sipissubclassinst:9,buffer:[1,4,14,10,13,8],simplewrapp:[13,10,4],foo:[13,10,8],dd_next:8,"__ne__":12,sensibl:10,repositori:5,sipenum_:4,"super":[0,4,8,10,12,13,14],customw:7,pyarg_parsetupl:[12,10,4],py_modulegetdict:10,obj:[9,10,14,4],chronolog:0,"__mul__":12,produc:5,ppc:2,py_decref:10,regist:[13,4],"__dtor__":5,encod:[0,10,8,4],bound:[10,8,4],down:0,right:[0,10,11],"__and__":12,sipcanconverttoenum:4,often:[13,10,11],accordingli:13,suffici:3,segment:[13,10],support:[0,1,2,3,4,5,6,8,9,10,12,13,14],why:[13,10],avail:[2,3,4,5,9,10,12,13],reli:9,extra_cxxflag:0,siptransf:9,siptype_qpoint:10,gil:[10,6,8,13,4],qtcore:[0,10],"__isub__":12,form:[0,6,2,13],forc:8,heap:[13,10,14,4],"true":[12,1,14,8],arrays:8,sipgetpyobject:4,tell:13,sip_except:[12,10],minor:4,hierachi:13,sip_unicodeerror:12,emit:[12,8,4],featur:[0,1,5,6,9,10,12,13,8],initialisationcod:[12,13,10],classic:[12,1],sipforceconverttoinst:[9,4],"abstract":[5,10,8],exist:[0,2,4,6,10,14],trip:12,bmake:0,py_lib_dir:0,when:[0,1,2,4,5,6,8,10,11,12,13,14],test:4,asstr:14,intend:[0,13,10,11],sipenum_klass_enum:4,sipsimplewrapp:[9,10,4],longer:[9,10],sip_pyslic:[12,8],ignor:[0,4,14,10,13,8],sipcppptr:10,time:[0,4,5,6,8,10,13,14],leftmargin:0,sip_attributeerror:12,concept:[5,13],skip:[13,10],global:[1,4,5,6,10,12,13,8],signific:[10,6,8],supplement:10,raisecod:[12,10],"__rshift__":12,depend:[0,2,4,9,10,8],unpack:2,decim:0,riverbank:10,cobject:14,sip_mod_dir:0,sourc:[0,5,6,2,10],string:[0,4,8,10,12,13,14],extra_lib_dir:0,convertfromtypecod:[9,10],"__bool__":12,word:[13,10,11,3,8],exact:[12,13,10,8],administr:2,level:10,did:[0,9],gui:[0,5,7],pylist_new:10,"0x0001":14,sipstringtypeclassmap:4,dir:[0,6,2],prevent:[13,7,10,8,4],core:3,sipvoidptr_typ:4,sign:12,minimis:5,port:2,appear:[10,8],gcclearcod:[12,10],current:[0,13,10,8,4],qscintilla:6,sipdelayeddtor:8,iarr:[12,10],deriv:[0,1,4,7,10,11,12,13,8],gener:[0,1,2,4,5,6,8,9,10,11,12,13,14],explicitli:[2,5,8,9,10,12,13,14],address:[8,10,14,4],"__hex__":14,sip_runtimeerror:12,along:10,"__repr__":12,convertor:[9,4],extra:[0,13,6,8,4],modul:[0,1,2,3,4,5,6,7,8,9,10,11,12,13,14],prefer:10,pyobject_typecheck:4,sip_slot_di:12,instal:[0,1,2,5,7,13],sipregisterpytyp:[13,10,4],moduleheadercod:[12,10],memori:[4,5,14,10,13,8],univers:[0,2],visit:10,sipfindnamedenum:[9,4],siptypenam:4,msg:0,scope:[12,10,8,4],siptype_qtimerev:10,sip_pytupl:[12,10,8],scite:6,pyqwt:0,claus:[10,8],templat:[0,5,10,12,13],pyerr_except:10,uniqu:[10,4],descriptor:13,can:[0,2,3,4,5,6,7,8,9,10,11,12,13,14],purpos:[0,10,14,4],encapsul:[0,5],isdelet:14,occur:[0,10,8],alwai:[5,13,10,4],multipl:[10,2,8,13],"__license__":10,sipmalloc:[13,4],sip_protected_is_publ:[10,4],write:[0,4,5,7,10,13],pure:[0,2,5,10,13,8],sip_memoryerror:12,map:[1,4,5,10,12,13,8],"__next__":12,sipmodulemakefil:[0,13],mai:[0,2,4,5,6,8,7,10,12,13,14],underscor:[11,4],data:[5,12,10,11],practic:10,sipcallmethod:[9,10,4],sip_qobject:12,stdin:6,explicit:[12,10,8],inform:[0,5,6,10,12,13,14],"switch":10,preced:[0,8,11],combin:[0,10,4],callabl:[5,12,10],converttosubclasscod:[12,10,4],wrapinst:14,size_t:4,still:[13,9,10,7,8],pointer:[4,9,10,11,12,8],dynam:[13,7],entiti:10,conjunct:[10,8],disconnect:12,platform:[0,2,5,6,10,12,13],window:[0,2,5,6,7,13],main:[10,14],non:[0,4,7,10,13,8],"float":[12,8,4],siplenptr:10,contriv:10,initi:[10,4],qcustomev:10,now:[13,9,10,7],nor:10,introduct:[5,1],pykd:0,term:[5,10],name:[0,1,2,3,4,5,6,8,9,10,11,12,13,14],realist:13,transferback:[13,9,14,8,4],revers:13,revert:9,separ:[0,4,10,12,13,8],sipsimplewrapper_typ:4,sip_pycal:[12,8],compil:[0,2,4,5,6,9,10,12,13],sip_vers:[0,14,4],sip_standarderror:12,replac:[0,2,4,10,11,13],individu:[0,10],continu:10,wrap:[0,4,5,6,8,10,11,12,13,14],sipconvertfromsliceobject:4,happen:13,py_ssize_t:4,shown:10,settracemask:14,sipforceconverttomappedtyp:[9,4],space:0,"0x0010":14,bespok:0,correct:[2,4,7,10,13,8],earlier:[1,9,4],migrat:13,"byte":[8,10,14,4],unpredict:8,care:[0,13],setdefault:13,sipconverttovoidptr:4,thing:[13,10,14],pyslice_getindicesex:4,first:[0,4,6,10,12,13,14],oper:[5,8,9,10,12,13,14],reimplement:[0,10,8,4],directli:[11,4],onc:[2,8,4],arrai:[4,14,10,12,13,8],pyimport_importmodul:11,dump_object:10,open:10,sip_configur:[0,13],size:[0,2,4,6,8,10,14],given:[6,10,2,13,4],silent:10,convent:10,sippi:10,caught:[10,8],convention:13,conveni:[10,4],editor:6,especi:5,copi:[0,4,8,7,10,12,13,14],specifi:[0,2,4,5,8,10,12,13,14],pyqt4:[13,10,8],enclos:[10,6,4],than:[0,2,4,8,7,10,13,14],virtualcatchercod:[12,10,4],wide:[1,13,4],py_vers:0,were:[0,9],posit:[0,8],pre:10,sai:13,ani:[0,2,3,4,5,6,7,9,10,12,13,8],properli:[5,12,13],techniqu:7,sipconvertfromsequenceindex:4,note:[4,7,10,11,12,13,8],take:[0,2,7,10,12,13,8],noth:[12,10],begin:[10,4],sure:[10,2,13,4],trace:[6,14],normal:[0,3,4,7,8,9,10,13,14],multipli:8,sipforceconverttotyp:4,pair:[0,8],homepag:5,later:[5,13,14,4],picklecod:[12,10],show:[10,2,8,11],"0x020303":0,"__irshift__":12,slot:[5,12,8],sipgetst:[10,4],onli:[0,4,5,10,12,13,8],slow:0,activ:12,state:[10,14,4],api_export_symbol:11,dict:[0,4],variou:[2,14,4],get:[0,2,4,10,11,13,8],cannon:0,soon:10,cannot:[12,10,8,11],requir:[0,2,4,5,8,7,10,13,14],mybool:8,borrow:4,pynam:[10,8],hellomodulemakefil:13,where:[0,4,5,10,12,13,14],pytyp:4,prehook:8,sipcpp:[12,10],concern:9,arg_nr:4,detect:[13,10,4],sippytyp:10,accesscod:[12,10],enumer:4,label:13,between:[4,5,10,11,12,13,8],"import":[0,3,4,5,6,7,10,11,12,13,14],across:13,sipwrappercheck:11,parent:13,style:[0,9],cycl:[13,4],setcod:[12,10],come:4,"0x0020":14,programmakefil:0,sipresolvetypedef:4,mani:[5,13,2,8],among:3,acceler:12,undocu:10,period:10,exploit:[5,13,10],colon:8,build_command:0,default_bin_dir:0,mark:14,siparg:10,derefer:10,thousand:13,ascobject:14,sip_indexerror:12,"__eq__":12,those:[0,13,10,8,4],"case":[0,8,10,11,12,13,14],defaultmetatyp:[12,13,10],py_typ:4,"__mod__":12,sip_arithmeticerror:12,cast:[12,9,10,14,4],invok:[0,5,10,3],invoc:8,sipreleasetyp:[10,8,4],margin:0,advantag:10,stdout:0,support_foo:10,them:[0,5,9,10,13],worri:5,myapi:13,ascii:[10,8,4],concatan:8,"__init__":[0,13,7,10,14],develop:[0,2,4,5,13,14],etc:10,same:[0,3,4,7,8,9,10,12,13,14],check:[0,2,4,10,11,14],ispyown:14,binari:[0,10,2,12],html:10,document:[5,10,6,13],metatyp:[13,10,14,8],nest:10,sipmethod:[10,4],footprint:13,appropri:[0,10,2,8,4],macro:[0,13,2,4],without:[0,4,5,10,12,13,8],sipmappedtyp:4,dereferenc:8,"__int__":[12,14],execut:[0,2,5,6,8,10,13,14],tip:6,rest:[10,4],releasegil:[10,6,8,13],siptransferobj:10,tobj:10,struct:[12,13,10],except:[0,1,2,4,5,6,8,10,11,12,13,14],littl:[12,13],real:[12,10],around:[0,4,8,9,10,12,14],read:[0,12,10,8],swig:5,world:13,part:[0,4,5,7,8,9,10,12,13,14],sip_ssize_t:[10,4],saniti:11,whitespac:[13,10],integ:[0,4,14,10,12,8],either:[0,2,3,4,8,10,13,14],output:10,manag:[1,10,8,13,4],wrappertyp:[13,10,14,4],pyconfig:0,ascend:4,slice:[12,4],definit:[1,4,5,10,12,8],siperrorfail:10,sip_assertionerror:12,exit:[0,8],notabl:6,freed:[13,4],mname:0,garbag:[13,10,8,4],cppptr:4,fulli:[0,4],immut:4,"throw":[12,10,8],comparison:[5,9],methodcod:[12,10,8,4],sip_stopiter:12,sipprotectvirt_foo:10,processor:10,slash:8,strip:0,pyobject_callobject:4,your:[0,1,2,3,5,7,9,13],macos_platform:10,generate_target_default:0,fast:5,mingw32:13,area:4,aren:13,hex:8,modulemakefil:[0,7],start:[0,4,5,8,10,13,14],compliant:4,interfac:[1,10,13],prot_is_publ:0,lot:0,timelin:[0,10,6,12,13],"__invert__":12,tupl:[0,12,10,8,4],py_end_allow_thread:[12,10],nmake:13,rightmargin:0,"default":[0,2,6,8,10,12,13,14],pylist_get_s:10,"__le__":12,embed:[1,10,11],deadlock:13,holdgil:[10,6,8,13],expect:[13,9,10,8,4],creat:[0,2,3,4,5,8,7,10,13,14],certain:[10,8,4],a0kei:10,file:[0,1,2,3,4,5,6,7,9,10,11,12,13,8],sip_taberror:12,again:[13,10,8],readi:0,q_object:13,reduct:6,tight:5,valid:[0,13,10,4],pathnam:0,you:[0,2,3,4,5,7,8,9,10,12,13,14],architectur:[0,2],noderiv:8,sequenc:[0,8,4],symbol:[0,10,9,2,4],docstr:[5,10,6,12,8],track:13,reduc:[13,2],directori:[0,2,3,5,6,7,10,13],descript:[0,10,6,12,4],stdexcept:10,py_initmodul:10,potenti:[1,9,10,13],cpp:[6,3,4],dst:0,represent:[0,10],all:[0,2,4,5,6,8,10,12,13,14],unencod:[10,8],capsul:14,sipconvertfrommappedtyp:[9,4],follow:[0,2,3,4,5,7,8,9,10,11,12,13,14],ptr:10,qt_4_2_0:13,"__cmp__":12,program:[0,13,14],sip_ioerror:12,sip_feature_:10,dd_isderiv:8,setdelet:14,introduc:[13,9],sipvisit:10,liter:13,far:9,util:[5,10],mechan:[5,13],fall:4,veri:[13,10],sipcppret:10,list:[0,2,3,5,6,10,12,13,8],posthook:8,siptypescop:4,adjust:0,hello_sip_flag:13,stderr:[0,10],small:[5,13],py_begin_allow_thread:[12,10],py_inc_dir:0,platform_lib:0,ten:13,interpretor:13,pyobject:[12,10,11,4],keeprefer:8,"__truediv__":[12,9],design:[5,8],pass:[0,4,6,7,9,10,11,13,8],what:[5,13,10],sub:[0,2,4,5,8,10,13,14],sipconverttoinst:[9,4],section:[9,10,8,4],abl:7,overload:[5,10],delet:[10,14],version:[0,1,2,3,4,5,6,8,9,10,12,13,14],"public":[0,4,6,10,12,13],hasn:[10,4],full:[0,2,4,5,6,10,12,13],themselv:10,sipfindmappedtyp:[9,4],sophist:5,behaviour:[13,9,10],sip_vmserror:12,modifi:[0,7],valu:[0,2,4,8,7,10,12,13,14],search:[10,6,13],helloconfig:13,"__xor__":12,prior:[9,10,4],amount:[10,8],via:[8,4],deprec:[4,5,8,9,10,14],inappropri:4,sipbadlengthforslic:4,select:13,hexadecim:[0,14,4],win32_platform:10,sip_sign:12,two:[0,2,9,10,12,13],taken:[0,10,4],sip_oserror:12,more:[0,1,2,4,6,10,13,8],desir:[10,8],sip_block_thread:[10,4],c_api:11,hundr:13,ital:10,flag:[0,5,10,13,4],bireleasebuffercod:[12,10],particular:[0,7,9,10,13,8],known:[14,4],destin:0,cach:4,none:[0,13,10,14,8],sipprotect_foo:10,remain:[12,10,4],pylist_check:10,v2_0:10,def:13,share:[5,4],accept:8,sipreleaseinst:[9,4],cours:11,newlin:0,rather:[0,4,8,7,10,13,14],anoth:[0,4,5,8,10,13,14],siperrorcontinu:10,divis:[12,1],sipinttypeclassmap:4,simpl:[0,1,3,5,12,13],referenc:[10,11,4],api_wrapper_check:11,sip_windowserror:12,compulsori:[10,8],sipconfig:[0,5,7,2,13],generate_target_instal:0,associ:[13,8,10,14,4],circumst:14,"short":[12,10,8,4],qtgui:[0,13,10],required_str:0,children:13,caus:[2,4,6,14,13,8],callback:5,help:[0,5,6,2],a_mod:10,i386:2,through:[0,10],hierarchi:[12,13,10,4],implicitli:[9,14,8],paramet:[0,8,6,14,4],typedef:[12,1,10,8,4],scon:0,might:[0,12,10,8,13],good:[10,2],"return":[0,4,8,10,11,13,14],timestamp:[10,8],exportedheadercod:[12,10],framework:0,somebodi:13,converttotypecod:[12,9,10,8,4],complain:8,"0x0008":14,easili:10,alreadi:[8,10,14,11,4],compris:5,found:[0,13,4],unicod:[13,10,8,4],"0x0004":14,inplac:[12,10],"0x0002":14,hard:13,idea:2,connect:[5,12,8],notypenam:8,event:10,setsiz:14,publish:13,print:10,occurr:10,siptype_klass:[10,4],qualifi:[10,4],sipwrapper_typ:4,reason:[13,10],base:[0,4,5,10,12,14],sbf:13,ask:10,earliest:[0,10],pylist_get_item:10,thread:[0,5,10,8,13],pycobject_check:11,omit:[12,10,6,8],perhap:7,lifetim:5,assign:[13,4],siptypeisnamespac:4,major:[2,4],default_mod_dir:[0,13],obviou:13,upper:[10,8,4],number:[0,1,2,4,5,6,8,10,12,13,14],extern:[5,10,8],done:[13,10],construct:[13,10],stabl:5,miss:9,build_ext:3,"__float__":12,gpl:[5,10],differ:[0,2,5,8,9,10,12,13,14],script:[0,2,3,5,7,10,13],interact:13,least:13,mfile:0,"__ixor__":12,store:10,option:[0,2,3,4,5,6,7,8,9,10,13,14],relationship:[13,4],siptransferbreak:[13,4],getter:[13,4],pars:[0,10,8],std:10,version_to_sip_tag:0,cyclic:[13,10,8,4],remov:[0,13,9,8,4],sip_api_minor_nr:4,str:8,consumpt:5,chkdir:0,comput:[10,8],create_config_modul:[0,13],tp_name:[8,4],packag:[0,10,7,2,8],"null":[10,11,4],sipkwd:10,"0x040000":[0,14,4],built:[0,5,7,10,2],lib:[13,2],self:[0,13,10],"__div__":[12,9],also:[0,2,4,5,6,7,10,11,13,8],build:[0,1,2,3,4,5,6,7,10,13],distribut:[5,7,2],exec:8,klassinst:10,previou:[13,8,10,14,4],defaultencod:[12,10,8],most:[12,10,6,14,4],maco:[0,5,2],addr:14,clear:10,cover:[5,10,2,13],transferobj:4,supertyp:[13,10,8],extra_lflag:0,latest:[0,5,10,2],microsoft:2,getcod:[12,10],particularli:14,sip_rxobj_con:[12,8],unitcod:[12,10],fine:[0,13,2],find:[5,13,8],copyright:[5,10],keyreleas:10,express:[0,12,10],py_non:[10,4],mappedtyp:[12,10],setdata:10,"_c_api":11,catcher:10,whenev:[13,9,10,8],common:[5,10,14],sip_unboundlocalerror:12,noreleas:8,set:[0,2,4,5,6,8,10,11,13,14],dump:14,mutabl:[14,4],extra_include_dir:0,sipr:10,arg:4,"__imod__":12,pythonw:7,call_exec:8,someth:[13,9,2],siptypeisenum:4,smallest:0,subdir:0,altern:[5,13,8],signatur:[4,5,6,9,10,12,8],latin:[10,8,4],numer:[0,8],disallow:[10,4],sipiserr:10,complementari:[5,9],popul:[13,10,4],both:[0,4,5,10,12,13,8],last:[12,13,10,8],license:[10,8],operat:12,context:[12,10,8,4],connectitem:12,load:[0,5,7,14],sipclass_klass:[10,4],simpli:[13,10],point:[4,14,10,12,13,8],instanti:[10,8],header:[0,2,5,10,11,13],linux:[5,6,7,2],throughout:10,compositemodul:[12,10],static_cast:10,empti:0,destructor:[4,5,8,10,12,13,14],extra_defin:0,strategi:13,sipconvertfromnamedenum:[9,4],convert:[0,2,4,6,10,11,13,8],sipreskei:10,understand:[5,12,14],"__lshift__":12,nodefaultctor:8,look:[6,7,2,8,13],sipreleasemappedtyp:[9,4],abov:[0,8,3],error:[0,10,8,4],"__hash__":12,anonym:4,sip_pylist:[12,8],sip_slot:12,readm:2,itself:[4,5,7,10,12,13],pytypeobject:[10,4],pyqt_sip_flag:13,sipmapstringtoclass:4,conflict:[13,6],behav:13,sym:4,temporari:[10,8,4],user:[9,7,4],"__add__":[12,10],wherev:10,chang:[0,4,5,9,10,13,8],travers:10,task:13,equival:[0,12,10,14,8],entri:[8,4],parenthes:4,pickl:10,sipflag:10,"__neg__":12,sip_rxobj_di:12,explan:10,getapi:14,dump_klass:10,siperrornon:10,restructuredtext:10,appli:[13,9,10,8,4],subsequ:[5,13,10,4],sip_pytyp:[12,8],format:[0,2,4,9,10,8],"__gt__":12,bit:14,pystring_fromstringands:10,formal:12,semi:12,signal:[5,12,8,4],resolv:0,collect:[12,13,10,8,4],api:[0,1,4,5,6,7,8,9,10,11,12,13,14],maplen:4,version_to_str:0,nbyte:4,sip_floatingpointerror:12,creation:5,some:[4,5,6,8,7,10,12,13,14],back:[0,8],siptype_qwidget:10,transferthi:[13,8],pep:4,larg:[5,13,10],recognis:10,pystring_asstringands:10,run:[5,10,2,3,13],siptransferto:[13,14,4],reach:13,step:[2,4],impos:10,sipconverttomappedtyp:[9,4],idx:4,block:[5,6,14,10,13,8],primarili:8,within:[10,8,4],ellipsi:8,hex_:8,ensur:[0,4,5,10,13,8],next:[10,7,2,8,13],question:13,"long":[12,6,8,4],custom:[0,1,7,2],handler:[13,4],sipseg:10,suit:0,forward:8,doctyp:8,sipmoduledict:10,siptype_qkeyev:10,link:[0,13,7,10,8],translat:10,line:[0,1,2,3,6,7,8,9,10,12,13,14],sdk:[0,2],getwrapp:[10,8],concaten:10,utf:[10,8,4],consist:12,bigetcharbuffercod:[12,10],py_buildvalu:[10,4],similar:[5,13,8,4],install_fil:0,sipconvertfromconstvoidptr:4,newthread:8,dd_list:8,sip_unicodeencodeerror:12,parser:[12,13,8],doesn:[0,12,10,13,4],repres:[0,4,14,12,13,8],"char":[12,13,10,8,4],sipdir:2,sipmodul:10,invalid:0,keywordarg:8,bracket:[10,4],librari:[0,2,5,6,7,10,12,13,14],clean:0,eval:4,unaffect:4,an_object_refer:9,leak:[13,10,8,4],hello:13,sip_referenceerror:12,install_dir:0,code:[0,1,2,4,5,6,8,9,10,11,12,13,14],sipconvertfromenum:4,results:8,qtguimodulemakefil:13,the_word:13,privat:[5,12,8,13],sens:12,generate_target_clean:0,sip_valueerror:12,sip_no_convertor:[10,4],typeheadercod:[12,13,10],sipconnectrx:9,siperrorfail1:10,relev:5,tri:[10,8],sipbuildresult:[9,4],"try":[10,6,14,13],refer:[0,1,4,5,8,10,11,13,14],sub_cfg:[0,13],sipdistutil:[5,3],impli:[0,8],smaller:13,cfg:[13,3],contructor:10,download:[5,1,2],append:[0,10,2,13],compat:[0,10,2,8,4],index:4,defaultsupertyp:[12,13,10],access:[0,4,5,6,10,12,13],sipexception_:4,consolid:[5,10],parse_build_macro:0,len:4,bodi:10,let:13,becom:[11,4],great:5,convers:[4,5,9,10,12,8],broken:4,pycobject_asvoidptr:11,typic:[0,13,9,10],chanc:13,siptype_typ:10,sip_not_non:[10,4],"boolean":[12,8,4],sipptrptr:10,sipexception_klass_except:4,from:[0,2,3,4,5,6,7,9,10,11,12,13,8],zip:2,doubl:[12,8,4],qobject:[12,13,10],implic:13,few:12,sip_unblock_thread:[10,4],sort:[13,6,4],rich:5,src:0,greatli:10,augment:0,annot:[1,4,6,9,10,12,13,8],bigetwritebuffercod:[12,10],obvious:13,thin:[12,4],proprietari:7,control:[13,10,4],sipgetwrapp:[9,4],tar:2,process:[5,10,3],lock:[1,4,5,6,10,13,8],tag:[0,13,6],fprintf:10,msvc:0,delai:8,gcc:2,sip:[0,1,2,3,4,5,6,7,8,9,10,11,12,13,14],sit:0,pyqt:[0,5,9,10,13],"__pos__":12,instead:[12,13,10,8,4],preinitialisationcod:[12,10],overridden:10,pymodule_getdict:11,alloc:[13,4],bind:[0,2,5,6,13,14],correspond:[0,2,4,5,10,11,12,13,8],element:[0,12,10,8,4],issu:[5,13,8],siperrorst:[10,4],allow:[0,2,4,5,7,9,10,12,13,8],siptypefrompytypeobject:4,typecod:[12,10],siptransferback:[13,14,4],comma:[12,13,8],py_conf_inc_dir:0,sipconvertfromnewinst:[9,4],destroi:[13,10,8,4],srcdir:0,therefor:[5,13],sipfre:[13,4],crash:[13,14],greater:[0,8,10,14,4],"__getitem__":[12,8],python:[0,1,2,3,4,5,6,7,8,9,10,11,12,13,14],auto:6,generate_macros_and_rul:0,nokia:5,qmake:0,"__delitem__":[12,8],postinitialisationcod:[12,10],anyth:8,modulecod:[12,10,8],subset:12,meta:[1,4,5,10,13,8],"static":[0,2,4,5,7,10,12,13],sipklass:[12,4],our:[13,3],special:[12,9,3],out:[5,13,2,8,4],variabl:[1,5,10,12,13,8],influenc:4,stub:[7,10],suitabl:5,rel:0,leverag:3,vendorid:7,q_slot:12,standalon:10,qtmod:10,dictionari:[0,4,10,11,12,13],releas:[2,4,5,6,10,13,8],afterward:[10,6,8],unnam:[10,14,8],opengl:0,timer:10,keep:[13,10],sipconvertfromnewtyp:4,length:[5,10,4],outsid:12,optional_list:0,softwar:[5,2],suffix:6,date:[13,2],owner:[14,4],parse_build_fil:0,facil:[0,6],typestr:4,transferto:14,dd_ptr:8,unknown:[14,8],licens:[5,1,10,12,8],sipparseresult:[9,10,4],system:[0,1,2,3,4,5,6,7,13],wrapper:[0,4,5,6,8,10,12,13,14],attach:10,termin:[13,10,8,4],"final":[10,2,13],sipclass_:4,"__del__":14,sip_systemexit:12,exactli:10,cmodul:[12,13,10],qevent:10,bother:13,see:[0,2,3,4,5,6,10,11,12,13,8],structur:[1,4,5,6,8,9,10,11,13,14],charact:[0,1,4,9,10,12,13,8],nocopi:8,slicelength:4,sipapidef:11,linker:[0,5,13],clearli:10,clib:0,sip_inc_dir:0,pyqt_sip_dir:13,need:[0,2,3,4,5,6,7,9,10,11,12,13,8],turn:10,tidi:10,verbatim:13,sip_typeerror:12,"0x04":4,"0x01":4,"0x02":4,builtin:[0,1,2,8,7,14],"_qt":10,which:[0,2,3,4,5,6,7,8,9,10,12,13,14],singl:[0,5,10,12,13],regard:[13,10,8,4],unless:[10,8],clash:[10,8],deploy:[13,10],pyd:5,"class":[0,1,4,5,6,8,7,10,12,13,14],siptype_:4,request:4,snapshot:[0,14,4],determin:[13,8,10,14,4],siptyp:10,constrain:[9,8],keypress:10,fact:5,extra_lib:[0,13],a0wrapp:10,text:[0,13,10],bring:5,sip_unicodedecodeerror:12,dbu:10,anywai:[10,8],locat:[13,4],sip_config_arg:0,should:[0,2,4,7,9,10,12,13,8],local:[10,3],hope:13,meant:[9,8],memcpi:10,increas:0,extract:[0,5,10],enabl:[0,4,6,8,10,13,14],sipconverttotyp:[10,4],possibl:[5,12,10,14,8],integr:[5,8],contain:[0,4,5,6,7,10,11,12,13,8],pylong_asunsignedlong:4,attribut:[0,1,13,11,4],sipexportsymbol:[11,4],sipwrappertype_typ:4,pyobject_print:10,correctli:[12,13],pattern:[0,10],dll:13,written:[0,5],neither:13,kei:[0,13,10],"__ifloordiv__":12,job:10,strdefin:0,"__ilshift__":12,addit:[0,1,4,9,10,12,13,8],consolidatedmodul:[12,10,6],use_arch:0,equal:[13,8,10,14,4],"__ior__":12,instanc:[0,4,5,8,10,11,12,13,14],comment:7,hyphen:8,py_xdecref:10,respect:[13,4],siplong_asunsignedlong:4,compon:[5,1,6,2,10],treat:[14,8],immedi:[10,8],"__itruediv__":12,ob_typ:4,togeth:5,sipbuff:10,dstdir:0,"__iadd__":12,defin:[0,2,4,5,8,9,10,11,12,13,14],typeint:4,"__floordiv__":12,"__sub__":12,noargpars:[10,8],helper:[10,4],reacquir:[10,6,8],sip_version_str:[0,14,4],sipattrgetterfunc:4,sip_temporari:[10,8],unneed:[0,10],member:[12,9,10,8,11],handl:[0,8,7,10,13,14],sip_environmenterror:12,http:[5,2],sipmapinttoclass:4,effect:[12,13,10],dealloc:10,distutil:[0,1,13,3,5],sipisapien:4,firstli:13,whole:13,ext_modul:3,exampl:[0,1,2,3,4,7,10,11,12,13,8],command:[0,1,2,3,6,7,8,9,10,13,14],choos:[5,10,8],undefin:10,usual:[0,10,8,3,4],unari:12,less:[13,10,8,4],obtain:[8,11,4],optional_str:0,"__lt__":12,prepend:10,field:8,makefil:[0,13,7,6],sip_anyslot:12,add:[13,10],ws_win:13,match:[5,12,10,8,13],sip_bin:[0,13],piec:10,siptypedef:[10,4],know:[12,10],recurs:10,insert:0,pyerr_occur:4,like:[2,4,7,9,10,13,8],success:4,build_macro:0,necessari:[0,5,9,10,11,12,13],suppli:[13,8,4],destdir:2,"export":[0,10,11,4],sippyself:10,win32:2,borland:2,"__contains__":12,qlist:10,avoid:[0,10,6,8,13],numdefin:0,overlap:8,leav:13,hello_sip_dir:13,sipconvertfromconstvoidptrands:4,"enum":[1,4,9,10,11,12,8],although:2,offset:4,stage:7,about:[5,6,14,8],actual:[13,10,8,11],"__imul__":[12,10],sipconverttocpp:9,statement:[12,10,6,14],includ:[0,2,4,5,6,8,10,11,12,13,14],constructor:[0,4,6,8,10,12,13,14],fals:12,discard:8,disabl:[0,6,10,2,14],own:[0,5,8,7,10,13,14],sipwrapper_check:[9,4],automat:[0,4,5,6,8,9,10,13,14],pyqtwrappertyp:10,"__abs__":12,merg:[13,10],transfer:[13,9,10,8,4],sip_notimplementederror:12,sipconvertfromvoidptr:4,sip_modul:11,"function":[0,1,4,5,6,8,9,10,11,12,13,14],unexpect:4,sip_systemerror:12,neutral:0,sipfindtyp:[11,4],bug:4,count:[13,10,4],made:[13,10,8,4],parentmakefil:0,whether:10,wish:2,writeabl:[14,4],displai:[0,6,2,14],limit:[13,10],otherwis:[10,2,8,4],problem:[0,13,8],"int":[12,9,10,8,4],mask:14,dure:[0,5,10,6],sipbadcatcherresult:4,filenam:[0,10],posix_platform:10,implement:[0,4,5,6,8,9,10,12,13,14],sipexception_std_except:10,mutual:[13,10],sip_pyobject:[12,8],detail:[0,2,4,5,10,12,13,8],virtual:[4,5,8,10,12,13,14],other:[0,2,4,5,10,12,13,8],bool:[12,8,10,14,4],futur:14,rememb:10,unwrapinst:14,repeat:8,pyerr_setnon:10,exporteddoc:[12,10,6],singleton:8,optionalinclud:[12,10],rule:0,klass:[12,10,4],"__index__":12,sipclassnam:[9,4]},titles:["The Build System","SIP Reference Guide","Installation","Building Your Extension with distutils","C API for Handwritten Code","Introduction","The SIP Command Line","Builtin Modules and Custom Interpreters","Annotations","Potential Incompatibilities with Earlier Versions","Directives","Using the C API when Embedding","SIP Specification Files","Using SIP","Python API for Applications"],modules:{sipconfig:0,sip:14},descrefs:{"":{sipGetState:[4,0],sipTransferTo:[4,0],SIP_VERSION:[4,3],sipSimpleWrapper:[4,5],sipFindMappedType:[4,0],SIP_API_MAJOR_NR:[4,3],sipLong_AsUnsignedLong:[4,0],sipConvertFromEnum:[4,0],sipIntTypeClassMap:[4,5],dd_name:[8,6],sipConvertFromInstance:[4,0],sipReleaseType:[4,0],SIP_NO_CONVERTORS:[4,3],sipTypeName:[4,0],sipConvertToInstance:[4,0],sipMapIntToClass:[4,0],sipFindType:[4,0],sipConvertFromType:[4,0],sipTypeIsEnum:[4,0],sipSimpleWrapper_Type:[4,8],sipConvertFromSliceObject:[4,0],sipForceConvertToMappedType:[4,0],sipTypeIsNamespace:[4,0],sipConvertToVoidPtr:[4,0],sipCanConvertToType:[4,0],sipCanConvertToInstance:[4,0],sipConvertFromConstVoidPtrAndSize:[4,0],typeString:[4,6],sipForceConvertToType:[4,0],dd_next:[8,6],sipExportSymbol:[4,0],sipBadLengthForSlice:[4,0],sipConvertToMappedType:[4,0],sipTypeAsPyTypeObject:[4,0],sipIsAPIEnabled:[4,0],sipTypeFromPyTypeObject:[4,0],sipForceConvertToInstance:[4,0],sipConvertFromVoidPtrAndSize:[4,0],sipReleaseMappedType:[4,0],sipStringTypeClassMap:[4,5],SIP_API_MINOR_NR:[4,3],sipVoidPtr_Type:[4,8],sipFree:[4,0],sipRegisterAttributeGetter:[4,0],sipConvertToType:[4,0],sipWrapperType:[4,5],sipConvertFromNewType:[4,0],SIP_PROTECTED_IS_PUBLIC:[4,3],dd_ptr:[8,6],sipConvertFromSequenceIndex:[4,0],SIP_VERSION_STR:[4,3],sipTypeIsMapped:[4,0],SIP_NOT_NONE:[4,3],sipClassName:[4,0],sipMapStringToClass:[4,0],sipWrapperType_Type:[4,8],sipConvertFromNewInstance:[4,0],sipTransferBack:[4,0],sipMalloc:[4,0],sipConvertFromMappedType:[4,0],sipWrapper:[4,5],dd_isderived:[8,6],sipConvertFromConstVoidPtr:[4,0],sipTypeIsClass:[4,0],sipBadCatcherResult:[4,0],sipGetPyObject:[4,0],SIP_UNBLOCK_THREADS:[4,3],sipDelayedDtor:[8,5],sipReleaseInstance:[4,0],sipWrapper_Check:[4,0],sipTransferBreak:[4,0],typeInt:[4,6],sipTypeScope:[4,0],sipImportSymbol:[4,0],sipDelayedDtors:[8,0],sipFindClass:[4,0],sipResolveTypedef:[4,0],sipConvertFromNamedEnum:[4,0],SIP_BLOCK_THREADS:[4,3],sipGetWrapper:[4,0],sipBadCallableArg:[4,0],sipFindNamedEnum:[4,0],user:[4,6],sipCanConvertToEnum:[4,0],sipCanConvertToMappedType:[4,0],sipWrapper_Type:[4,8],sipCallMethod:[4,0],sipParseResult:[4,0],sipBuildResult:[4,0],sipRegisterPyType:[4,0],SIP_SSIZE_T:[4,3],sipConvertFromVoidPtr:[4,0]},"sipconfig.PythonModuleMakefile":{generate_target_install:[0,1],generate_macros_and_rules:[0,1],"__init__":[0,1]},sip:{transferto:[14,2],getapi:[14,2],settracemask:[14,2],setdeleted:[14,2],dump:[14,2],transferback:[14,2],SIP_VERSION_STR:[14,9],ispyowned:[14,2],wrapper:[14,7],cast:[14,2],unwrapinstance:[14,2],setapi:[14,2],wrapinstance:[14,2],SIP_VERSION:[14,9],voidptr:[14,7],wrappertype:[14,7],isdeleted:[14,2],"delete":[14,2]},"sip.voidptr":{"__int__":[14,1],getwriteable:[14,1],setwriteable:[14,1],ascobject:[14,1],ascapsule:[14,1],getsize:[14,1],"__hex__":[14,1],asstring:[14,1],setsize:[14,1],"__init__":[14,1]},"sipconfig.ProgramMakefile":{generate_target_default:[0,1],build_command:[0,1],generate_macros_and_rules:[0,1],generate_target_clean:[0,1],generate_target_install:[0,1],finalise:[0,1],"__init__":[0,1]},"sipconfig.ParentMakefile":{generate_target_clean:[0,1],generate_target_install:[0,1],generate_target_default:[0,1],generate_macros_and_rules:[0,1],"__init__":[0,1]},sipconfig:{create_config_module:[0,2],ModuleMakefile:[0,7],Configuration:[0,7],create_wrapper:[0,2],version_to_sip_tag:[0,2],format:[0,2],parse_build_macros:[0,2],create_content:[0,2],ParentMakefile:[0,7],Makefile:[0,7],read_version:[0,2],inform:[0,2],error:[0,2],version_to_string:[0,2],ProgramMakefile:[0,7],SIPModuleMakefile:[0,7],PythonModuleMakefile:[0,7]},"sipconfig.ModuleMakefile":{generate_target_default:[0,1],generate_macros_and_rules:[0,1],generate_target_clean:[0,1],module_as_lib:[0,1],generate_target_install:[0,1],finalise:[0,1],"__init__":[0,1]},"sipconfig.Makefile":{chkdir:[0,4],platform_lib:[0,1],install_file:[0,1],ready:[0,1],extra_libs:[0,4],"__init__":[0,1],generate_target_default:[0,1],console:[0,4],generator:[0,4],extra_include_dirs:[0,4],clean_build_file_objects:[0,1],mkdir:[0,4],extra_cflags:[0,4],rm:[0,4],extra_lib_dirs:[0,4],config:[0,4],finalise:[0,1],required_string:[0,1],extra_cxxflags:[0,4],extra_lflags:[0,4],parse_build_file:[0,1],generate_target_clean:[0,1],copy:[0,4],generate_target_install:[0,1],generate:[0,1],optional_string:[0,1],optional_list:[0,1],generate_macros_and_rules:[0,1],extra_defines:[0,4]},"sipconfig.SIPModuleMakefile":{finalise:[0,1],"__init__":[0,1]},"sipconfig.Configuration":{set_build_macros:[0,1],default_mod_dir:[0,4],default_bin_dir:[0,4],platform:[0,4],universal:[0,4],sip_version:[0,4],sip_config_args:[0,4],default_sip_dir:[0,4],sip_mod_dir:[0,4],build_macros:[0,1],py_inc_dir:[0,4],sip_inc_dir:[0,4],py_conf_inc_dir:[0,4],py_version:[0,4],py_lib_dir:[0,4],arch:[0,4],sip_version_str:[0,4],"__init__":[0,1],sip_bin:[0,4]}},filenames:["build_system","index","installation","distutils","c_api","introduction","command_line","builtin","annotations","incompatibilities","directives","embedding","specification_files","using","python_api"]})
\ No newline at end of file diff --git a/doc/html/specification_files.html b/doc/html/specification_files.html new file mode 100644 index 0000000..e408fe4 --- /dev/null +++ b/doc/html/specification_files.html @@ -0,0 +1,612 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + + <title>SIP Specification Files — SIP 4.10.5 Reference Guide</title> + <link rel="stylesheet" href="_static/default.css" type="text/css" /> + <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '#', + VERSION: '4.10.5', + COLLAPSE_MODINDEX: false, + FILE_SUFFIX: '.html', + HAS_SOURCE: true + }; + </script> + <script type="text/javascript" src="_static/jquery.js"></script> + <script type="text/javascript" src="_static/doctools.js"></script> + <link rel="top" title="SIP 4.10.5 Reference Guide" href="index.html" /> + <link rel="next" title="Directives" href="directives.html" /> + <link rel="prev" title="The SIP Command Line" href="command_line.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="modindex.html" title="Global Module Index" + accesskey="M">modules</a> |</li> + <li class="right" > + <a href="directives.html" title="Directives" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="command_line.html" title="The SIP Command Line" + accesskey="P">previous</a> |</li> + <li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="sip-specification-files"> +<h1>SIP Specification Files<a class="headerlink" href="#sip-specification-files" title="Permalink to this headline">¶</a></h1> +<p>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.</p> +<p>It is important to understand that a SIP specification describes the Python +API, i.e. the API available to the Python programmer when they <tt class="docutils literal"><span class="pre">import</span></tt> 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.</p> +<p>In most cases the Python API matches the C/C++ API. In some cases handwritten +code (see <a class="reference external" href="directives.html#directive-%MethodCode"><tt class="xref docutils literal"><span class="pre">%MethodCode</span></tt></a>) 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 +<a class="reference external" href="c_api.html#ref-derived-classes"><em>Generated Derived Classes</em></a>) and needs to know the exact C++ signature. To deal +with these cases SIP allows two signatures to be specified. For example:</p> +<div class="highlight-python"><pre>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 +};</pre> +</div> +<div class="section" id="syntax-definition"> +<h2>Syntax Definition<a class="headerlink" href="#syntax-definition" title="Permalink to this headline">¶</a></h2> +<p>The following is a semi-formal description of the syntax of a specification +file.</p> +<pre class="literal-block"> +<em>specification</em> ::= {<em>module-statement</em>} + +<em>module-statement</em> ::= [<em>module-directive</em> | <em>statement</em>] + +<em>module-directive</em> ::= [ + <a class="reference external" href="directives.html#directive-%API"><tt class="xref docutils literal"><span class="pre">%API</span></tt></a> | + <a class="reference external" href="directives.html#directive-%CModule"><tt class="xref docutils literal"><span class="pre">%CModule</span></tt></a> | + <a class="reference external" href="directives.html#directive-%CompositeModule"><tt class="xref docutils literal"><span class="pre">%CompositeModule</span></tt></a> | + <a class="reference external" href="directives.html#directive-%ConsolidatedModule"><tt class="xref docutils literal"><span class="pre">%ConsolidatedModule</span></tt></a> | + <a class="reference external" href="directives.html#directive-%Copying"><tt class="xref docutils literal"><span class="pre">%Copying</span></tt></a> | + <a class="reference external" href="directives.html#directive-%DefaultEncoding"><tt class="xref docutils literal"><span class="pre">%DefaultEncoding</span></tt></a> | + <a class="reference external" href="directives.html#directive-%DefaultMetatype"><tt class="xref docutils literal"><span class="pre">%DefaultMetatype</span></tt></a> | + <a class="reference external" href="directives.html#directive-%DefaultSupertype"><tt class="xref docutils literal"><span class="pre">%DefaultSupertype</span></tt></a> | + <a class="reference external" href="directives.html#directive-%Doc"><tt class="xref docutils literal"><span class="pre">%Doc</span></tt></a> | + <a class="reference external" href="directives.html#directive-%ExportedDoc"><tt class="xref docutils literal"><span class="pre">%ExportedDoc</span></tt></a> | + <a class="reference external" href="directives.html#directive-%ExportedHeaderCode"><tt class="xref docutils literal"><span class="pre">%ExportedHeaderCode</span></tt></a> | + <a class="reference external" href="directives.html#directive-%Feature"><tt class="xref docutils literal"><span class="pre">%Feature</span></tt></a> | + <a class="reference external" href="directives.html#directive-%Import"><tt class="xref docutils literal"><span class="pre">%Import</span></tt></a> | + <a class="reference external" href="directives.html#directive-%Include"><tt class="xref docutils literal"><span class="pre">%Include</span></tt></a> | + <a class="reference external" href="directives.html#directive-%InitialisationCode"><tt class="xref docutils literal"><span class="pre">%InitialisationCode</span></tt></a> | + <a class="reference external" href="directives.html#directive-%License"><tt class="xref docutils literal"><span class="pre">%License</span></tt></a> | + <a class="reference external" href="directives.html#directive-%MappedType"><tt class="xref docutils literal"><span class="pre">%MappedType</span></tt></a> | + <a class="reference external" href="directives.html#directive-%Module"><tt class="xref docutils literal"><span class="pre">%Module</span></tt></a> | + <a class="reference external" href="directives.html#directive-%ModuleCode"><tt class="xref docutils literal"><span class="pre">%ModuleCode</span></tt></a> | + <a class="reference external" href="directives.html#directive-%ModuleHeaderCode"><tt class="xref docutils literal"><span class="pre">%ModuleHeaderCode</span></tt></a> | + <a class="reference external" href="directives.html#directive-%OptionalInclude"><tt class="xref docutils literal"><span class="pre">%OptionalInclude</span></tt></a> | + <a class="reference external" href="directives.html#directive-%Platforms"><tt class="xref docutils literal"><span class="pre">%Platforms</span></tt></a> | + <a class="reference external" href="directives.html#directive-%PreInitialisationCode"><tt class="xref docutils literal"><span class="pre">%PreInitialisationCode</span></tt></a> | + <a class="reference external" href="directives.html#directive-%PostInitialisationCode"><tt class="xref docutils literal"><span class="pre">%PostInitialisationCode</span></tt></a> | + <a class="reference external" href="directives.html#directive-%Timeline"><tt class="xref docutils literal"><span class="pre">%Timeline</span></tt></a> | + <a class="reference external" href="directives.html#directive-%UnitCode"><tt class="xref docutils literal"><span class="pre">%UnitCode</span></tt></a> | + <em>mapped-type-template</em>] + +<em>statement</em> :: [<em>class-statement</em> | <em>function</em> | <em>variable</em>] + +<em>class-statement</em> :: [ + <a class="reference external" href="directives.html#directive-%If"><tt class="xref docutils literal"><span class="pre">%If</span></tt></a> | + <em>class</em> | + <em>class-template</em> | + <em>enum</em> | + <em>namespace</em> | + <em>opaque-class</em> | + <em>operator</em> | + <em>struct</em> | + <em>typedef</em> | + <em>exception</em>] + +<em>class</em> ::= <strong>class</strong> <em>name</em> [<strong>:</strong> <em>super-classes</em>] [<em>class-annotations</em>] + <strong>{</strong> {<em>class-line</em>} <strong>};</strong> + +<em>super-classes</em> ::= <em>name</em> [<strong>,</strong> <em>super-classes</em>] + +<em>class-line</em> ::= [ + <em>class-statement</em> | + <a class="reference external" href="directives.html#directive-%BIGetBufferCode"><tt class="xref docutils literal"><span class="pre">%BIGetBufferCode</span></tt></a> | + <a class="reference external" href="directives.html#directive-%BIGetReadBufferCode"><tt class="xref docutils literal"><span class="pre">%BIGetReadBufferCode</span></tt></a> | + <a class="reference external" href="directives.html#directive-%BIGetWriteBufferCode"><tt class="xref docutils literal"><span class="pre">%BIGetWriteBufferCode</span></tt></a> | + <a class="reference external" href="directives.html#directive-%BIGetSegCountCode"><tt class="xref docutils literal"><span class="pre">%BIGetSegCountCode</span></tt></a> | + <a class="reference external" href="directives.html#directive-%BIGetCharBufferCode"><tt class="xref docutils literal"><span class="pre">%BIGetCharBufferCode</span></tt></a> | + <a class="reference external" href="directives.html#directive-%BIReleaseBufferCode"><tt class="xref docutils literal"><span class="pre">%BIReleaseBufferCode</span></tt></a> | + <a class="reference external" href="directives.html#directive-%ConvertToSubClassCode"><tt class="xref docutils literal"><span class="pre">%ConvertToSubClassCode</span></tt></a> | + <a class="reference external" href="directives.html#directive-%ConvertToTypeCode"><tt class="xref docutils literal"><span class="pre">%ConvertToTypeCode</span></tt></a> | + <a class="reference external" href="directives.html#directive-%Docstring"><tt class="xref docutils literal"><span class="pre">%Docstring</span></tt></a> | + <a class="reference external" href="directives.html#directive-%GCClearCode"><tt class="xref docutils literal"><span class="pre">%GCClearCode</span></tt></a> | + <a class="reference external" href="directives.html#directive-%GCTraverseCode"><tt class="xref docutils literal"><span class="pre">%GCTraverseCode</span></tt></a> | + <a class="reference external" href="directives.html#directive-%PickleCode"><tt class="xref docutils literal"><span class="pre">%PickleCode</span></tt></a> | + <a class="reference external" href="directives.html#directive-%TypeCode"><tt class="xref docutils literal"><span class="pre">%TypeCode</span></tt></a> | + <a class="reference external" href="directives.html#directive-%TypeHeaderCode"><tt class="xref docutils literal"><span class="pre">%TypeHeaderCode</span></tt></a> | + <em>constructor</em> | + <em>destructor</em> | + <em>method</em> | + <em>static-method</em> | + <em>virtual-method</em> | + <em>special-method</em> | + <em>operator</em> | + <em>virtual-operator</em> | + <em>class-variable</em> | + <strong>public:</strong> | + <strong>public Q_SLOTS:</strong> | + <strong>public slots:</strong> | + <strong>protected:</strong> | + <strong>protected Q_SLOTS:</strong> | + <strong>protected slots:</strong> | + <strong>private:</strong> | + <strong>private Q_SLOTS:</strong> | + <strong>private slots:</strong> | + <strong>Q_SIGNALS:</strong> | + <strong>signals:</strong>] + +<em>constructor</em> ::= [<strong>explicit</strong>] <em>name</em> <strong>(</strong> [<em>argument-list</em>] <strong>)</strong> + [<em>exceptions</em>] [<em>function-annotations</em>] + [<em>c++-constructor-signature</em>] <strong>;</strong> [<a class="reference external" href="directives.html#directive-%Docstring"><tt class="xref docutils literal"><span class="pre">%Docstring</span></tt></a>] + [<a class="reference external" href="directives.html#directive-%MethodCode"><tt class="xref docutils literal"><span class="pre">%MethodCode</span></tt></a>] + +<em>c++-constructor-signature</em> ::= <strong>[(</strong> [<em>argument-list</em>] <strong>)]</strong> + +<em>destructor</em> ::= [<strong>virtual</strong>] <strong>~</strong> <em>name</em> <strong>()</strong> [<em>exceptions</em>] [<strong>= 0</strong>] + [<em>function-annotations</em>] <strong>;</strong> [<a class="reference external" href="directives.html#directive-%MethodCode"><tt class="xref docutils literal"><span class="pre">%MethodCode</span></tt></a>] + [<a class="reference external" href="directives.html#directive-%VirtualCatcherCode"><tt class="xref docutils literal"><span class="pre">%VirtualCatcherCode</span></tt></a>] + +<em>method</em> ::= [<strong>Q_SIGNAL</strong>] [<strong>Q_SLOT</strong>] <em>type</em> <em>name</em> <strong>(</strong> + [<em>argument-list</em>] <strong>)</strong> [<strong>const</strong>] [<em>exceptions</em>] [<strong>= 0</strong>] + [<em>function-annotations</em>] [<em>c++-signature</em>] <strong>;</strong> + [<a class="reference external" href="directives.html#directive-%Docstring"><tt class="xref docutils literal"><span class="pre">%Docstring</span></tt></a>] [<a class="reference external" href="directives.html#directive-%MethodCode"><tt class="xref docutils literal"><span class="pre">%MethodCode</span></tt></a>] + +<em>c++-signature</em> ::= <strong>[</strong> <em>type</em> <strong>(</strong> [<em>argument-list</em>] <strong>)]</strong> + +<em>static-method</em> ::= <strong>static</strong> <em>function</em> + +<em>virtual-method</em> ::= [<strong>Q_SIGNAL</strong>] [<strong>Q_SLOT</strong>] <strong>virtual</strong> <em>type</em> <em>name</em> + <strong>(</strong> [<em>argument-list</em>] <strong>)</strong> [<strong>const</strong>] [<em>exceptions</em>] [<strong>= 0</strong>] + [<em>function-annotations</em>] [<em>c++-signature</em>] <strong>;</strong> + [<a class="reference external" href="directives.html#directive-%MethodCode"><tt class="xref docutils literal"><span class="pre">%MethodCode</span></tt></a>] [<a class="reference external" href="directives.html#directive-%VirtualCatcherCode"><tt class="xref docutils literal"><span class="pre">%VirtualCatcherCode</span></tt></a>] + +<em>special-method</em> ::= <em>type</em> <em>special-method-name</em> + <strong>(</strong> [<em>argument-list</em>] <strong>)</strong> [<em>function-annotations</em>] <strong>;</strong> + [<a class="reference external" href="directives.html#directive-%MethodCode"><tt class="xref docutils literal"><span class="pre">%MethodCode</span></tt></a>] + +<em>special-method-name</em> ::= [<strong>__abs__</strong> | <strong>__add__</strong> | <strong>__and__</strong> | + <strong>__bool__</strong> | <strong>__call__</strong> | <strong>__cmp__</strong> | <strong>__contains__</strong> | + <strong>__delitem__</strong> | <strong>__div__</strong> | <strong>__eq__</strong> | <strong>__float__</strong> | + <strong>__floordiv__</strong> | <strong>__ge__</strong> | <strong>__getitem__</strong> | <strong>__gt__</strong> | + <strong>__hash__</strong> | <strong>__iadd__</strong> | <strong>__iand__</strong> | <strong>__idiv__</strong> | + <strong>__ifloordiv__</strong> | <strong>__ilshift__</strong> | <strong>__imod__</strong> | <strong>__imul__</strong> | + <strong>__index__</strong> | <strong>__int__</strong> | <strong>__invert__</strong> | <strong>__ior__</strong> | + <strong>__irshift__</strong> | <strong>__isub__</strong> | <strong>__iter__</strong> | <strong>__itruediv__</strong> | + <strong>__ixor__</strong> | <strong>__le__</strong> | <strong>__len__</strong> | <strong>__long__</strong> | + <strong>__lshift__</strong> | <strong>__lt__</strong> | <strong>__mod__</strong> | <strong>__mul__</strong> | + <strong>__ne__</strong> | <strong>__neg__</strong> | <strong>__next__</strong> | <strong>__nonzero__</strong> | + <strong>__or__</strong> | <strong>__pos__</strong> | <strong>__repr__</strong> | <strong>__rshift__</strong> | + <strong>__setitem__</strong> | <strong>__str__</strong> | <strong>__sub__</strong> | <strong>__truediv__</strong> | + <strong>__xor__</strong>] + +<em>operator</em> ::= <em>operator-type</em> + <strong>(</strong> [<em>argument-list</em>] <strong>)</strong> [<strong>const</strong>] [<em>exceptions</em>] + [<em>function-annotations</em>] <strong>;</strong> [<a class="reference external" href="directives.html#directive-%MethodCode"><tt class="xref docutils literal"><span class="pre">%MethodCode</span></tt></a>] + +<em>virtual-operator</em> ::= <strong>virtual</strong> <em>operator-type</em> + <strong>(</strong> [<em>argument-list</em>] <strong>)</strong> [<strong>const</strong>] [<em>exceptions</em>] [<strong>= 0</strong>] + [<em>function-annotations</em>] <strong>;</strong> [<a class="reference external" href="directives.html#directive-%MethodCode"><tt class="xref docutils literal"><span class="pre">%MethodCode</span></tt></a>] + [<a class="reference external" href="directives.html#directive-%VirtualCatcherCode"><tt class="xref docutils literal"><span class="pre">%VirtualCatcherCode</span></tt></a>] + +<em>operatator-type</em> ::= [ <em>operator-function</em> | <em>operator-cast</em> ] + +<em>operator-function</em> ::= <em>type</em> <strong>operator</strong> <em>operator-name</em> + +<em>operator-cast</em> ::= <strong>operator</strong> <em>type</em> + +<em>operator-name</em> ::= [<strong>+</strong> | <strong>-</strong> | <strong>*</strong> | <strong>/</strong> | <strong>%</strong> | <strong>&</strong> | + <strong>|</strong> | <strong>^</strong> | <strong><<</strong> | <strong>>></strong> | <strong>+=</strong> | <strong>-=</strong> | <strong>*=</strong> | + <strong>/=</strong> | <strong>%=</strong> | <strong>&=</strong> | <strong>|=</strong> | <strong>^=</strong> | <strong><<=</strong> | <strong>>>=</strong> | + <strong>~</strong> | <strong>()</strong> | <strong>[]</strong> | <strong><</strong> | <strong><=</strong> | <strong>==</strong> | <strong>!=</strong> | + <strong>></strong> | <strong>>>=</strong> | <strong>=</strong>] + +<em>class-variable</em> ::= [<strong>static</strong>] <em>variable</em> + +<em>class-template</em> :: = <strong>template</strong> <strong><</strong> <em>type-list</em> <strong>></strong> <em>class</em> + +<em>mapped-type-template</em> :: = <strong>template</strong> <strong><</strong> <em>type-list</em> <strong>></strong> + <a class="reference external" href="directives.html#directive-%MappedType"><tt class="xref docutils literal"><span class="pre">%MappedType</span></tt></a> + +<em>enum</em> ::= <strong>enum</strong> [<em>name</em>] [<em>enum-annotations</em>] <strong>{</strong> {<em>enum-line</em>} <strong>};</strong> + +<em>enum-line</em> ::= [<a class="reference external" href="directives.html#directive-%If"><tt class="xref docutils literal"><span class="pre">%If</span></tt></a> | <em>name</em> [<em>enum-annotations</em>] <strong>,</strong> + +<em>function</em> ::= <em>type</em> <em>name</em> <strong>(</strong> [<em>argument-list</em>] <strong>)</strong> [<em>exceptions</em>] + [<em>function-annotations</em>] <strong>;</strong> [<a class="reference external" href="directives.html#directive-%Docstring"><tt class="xref docutils literal"><span class="pre">%Docstring</span></tt></a>] + [<a class="reference external" href="directives.html#directive-%MethodCode"><tt class="xref docutils literal"><span class="pre">%MethodCode</span></tt></a>] + +<em>namespace</em> ::= <strong>namespace</strong> <em>name</em> <strong>{</strong> {<em>namespace-line</em>} <strong>};</strong> + +<em>namespace-line</em> ::= [<a class="reference external" href="directives.html#directive-%TypeHeaderCode"><tt class="xref docutils literal"><span class="pre">%TypeHeaderCode</span></tt></a> | <em>statement</em>] + +<em>opaque-class</em> ::= <strong>class</strong> <em>scoped-name</em> <strong>;</strong> + +<em>struct</em> ::= <strong>struct</strong> <em>name</em> <strong>{</strong> {<em>class-line</em>} <strong>};</strong> + +<em>typedef</em> ::= <strong>typedef</strong> [<em>typed-name</em> | <em>function-pointer</em>] + <em>typedef-annotations</em> <strong>;</strong> + +<em>variable</em>::= <em>typed-name</em> [<em>variable-annotations</em>] <strong>;</strong> + [<a class="reference external" href="directives.html#directive-%AccessCode"><tt class="xref docutils literal"><span class="pre">%AccessCode</span></tt></a>] [<a class="reference external" href="directives.html#directive-%GetCode"><tt class="xref docutils literal"><span class="pre">%GetCode</span></tt></a>] + [<a class="reference external" href="directives.html#directive-%SetCode"><tt class="xref docutils literal"><span class="pre">%SetCode</span></tt></a>] + +<em>exception</em> ::= <a class="reference external" href="directives.html#directive-%Exception"><tt class="xref docutils literal"><span class="pre">%Exception</span></tt></a> <em>exception-name</em> [<em>exception-base</em>] + <strong>{</strong> [<a class="reference external" href="directives.html#directive-%TypeHeaderCode"><tt class="xref docutils literal"><span class="pre">%TypeHeaderCode</span></tt></a>] <a class="reference external" href="directives.html#directive-%RaiseCode"><tt class="xref docutils literal"><span class="pre">%RaiseCode</span></tt></a> <strong>};</strong> + +<em>exception-name</em> ::= <em>scoped-name</em> + +<em>exception-base</em> ::= <strong>(</strong> [<em>exception-name</em> | <em>python-exception</em>] <strong>)</strong> + +<em>python-exception</em> ::= [<strong>SIP_Exception</strong> | <strong>SIP_StopIteration</strong> | + <strong>SIP_StandardError</strong> | <strong>SIP_ArithmeticError</strong> | + <strong>SIP_LookupError</strong> | <strong>SIP_AssertionError</strong> | + <strong>SIP_AttributeError</strong> | <strong>SIP_EOFError</strong> | + <strong>SIP_FloatingPointError</strong> | <strong>SIP_EnvironmentError</strong> | + <strong>SIP_IOError</strong> | <strong>SIP_OSError</strong> | <strong>SIP_ImportError</strong> | + <strong>SIP_IndexError</strong> | <strong>SIP_KeyError</strong> | <strong>SIP_KeyboardInterrupt</strong> | + <strong>SIP_MemoryError</strong> | <strong>SIP_NameError</strong> | <strong>SIP_OverflowError</strong> | + <strong>SIP_RuntimeError</strong> | <strong>SIP_NotImplementedError</strong> | + <strong>SIP_SyntaxError</strong> | <strong>SIP_IndentationError</strong> | <strong>SIP_TabError</strong> | + <strong>SIP_ReferenceError</strong> | <strong>SIP_SystemError</strong> | <strong>SIP_SystemExit</strong> | + <strong>SIP_TypeError</strong> | <strong>SIP_UnboundLocalError</strong> | + <strong>SIP_UnicodeError</strong> | <strong>SIP_UnicodeEncodeError</strong> | + <strong>SIP_UnicodeDecodeError</strong> | <strong>SIP_UnicodeTranslateError</strong> | + <strong>SIP_ValueError</strong> | <strong>SIP_ZeroDivisionError</strong> | + <strong>SIP_WindowsError</strong> | <strong>SIP_VMSError</strong>] + +<em>exceptions</em> ::= <strong>throw (</strong> [<em>exception-list</em>] <strong>)</strong> + +<em>exception-list</em> ::= <em>scoped-name</em> [<strong>,</strong> <em>exception-list</em>] + +<em>argument-list</em> ::= <em>argument</em> [<strong>,</strong> <em>argument-list</em>] [<strong>,</strong> <strong>...</strong>] + +<em>argument</em> ::= [ + <em>type</em> [<em>name</em>] [<em>argument-annotations</em>] [<em>default-value</em>] | + <a class="reference internal" href="#stype-SIP_ANYSLOT"><tt class="xref docutils literal"><span class="pre">SIP_ANYSLOT</span></tt></a> [<em>default-value</em>] | + <a class="reference internal" href="#stype-SIP_QOBJECT"><tt class="xref docutils literal"><span class="pre">SIP_QOBJECT</span></tt></a> | + <a class="reference internal" href="#stype-SIP_RXOBJ_CON"><tt class="xref docutils literal"><span class="pre">SIP_RXOBJ_CON</span></tt></a> | + <a class="reference internal" href="#stype-SIP_RXOBJ_DIS"><tt class="xref docutils literal"><span class="pre">SIP_RXOBJ_DIS</span></tt></a> | + <a class="reference internal" href="#stype-SIP_SIGNAL"><tt class="xref docutils literal"><span class="pre">SIP_SIGNAL</span></tt></a> [<em>default-value</em>] | + <a class="reference internal" href="#stype-SIP_SLOT"><tt class="xref docutils literal"><span class="pre">SIP_SLOT</span></tt></a> [<em>default-value</em>] | + <a class="reference internal" href="#stype-SIP_SLOT_CON"><tt class="xref docutils literal"><span class="pre">SIP_SLOT_CON</span></tt></a> | + <a class="reference internal" href="#stype-SIP_SLOT_DIS"><tt class="xref docutils literal"><span class="pre">SIP_SLOT_DIS</span></tt></a>] + +<em>default-value</em> ::= <strong>=</strong> <em>expression</em> + +<em>expression</em> ::= [<em>value</em> | <em>value</em> <em>binary-operator</em> <em>expression</em>] + +<em>value</em> ::= [<em>unary-operator</em>] <em>simple-value</em> + +<em>simple-value</em> ::= [<em>scoped-name</em> | <em>function-call</em> | <em>real-value</em> | + <em>integer-value</em> | <em>boolean-value</em> | <em>string-value</em> | + <em>character-value</em>] + +<em>typed-name</em>::= <em>type</em> <em>name</em> + +<em>function-pointer</em>::= <em>type</em> <strong>(*</strong> <em>name</em> <strong>)(</strong> [<em>type-list</em>] <strong>)</strong> + +<em>type-list</em> ::= <em>type</em> [<strong>,</strong> <em>type-list</em>] + +<em>function-call</em> ::= <em>scoped-name</em> <strong>(</strong> [<em>value-list</em>] <strong>)</strong> + +<em>value-list</em> ::= <em>value</em> [<strong>,</strong> <em>value-list</em>] + +<em>real-value</em> ::= a floating point number + +<em>integer-value</em> ::= a number + +<em>boolean-value</em> ::= [<strong>true</strong> | <strong>false</strong>] + +<em>string-value</em> ::= <strong>“</strong> {<em>character</em>} <strong>“</strong> + +<em>character-value</em> ::= <strong>‘</strong> <em>character</em> <strong>‘</strong> + +<em>unary-operator</em> ::= [<strong>!</strong> | <strong>~</strong> | <strong>-</strong> | <strong>+</strong>] + +<em>binary-operator</em> ::= [<strong>-</strong> | <strong>+</strong> | <strong>*</strong> | <strong>/</strong> | <strong>&</strong> | <strong>|</strong>] + +<em>argument-annotations</em> ::= see <a class="reference external" href="annotations.html#ref-arg-annos"><em>Argument Annotations</em></a> + +<em>class-annotations</em> ::= see <a class="reference external" href="annotations.html#ref-class-annos"><em>Class Annotations</em></a> + +<em>enum-annotations</em> ::= see <a class="reference external" href="annotations.html#ref-enum-annos"><em>Enum Annotations</em></a> + +<em>function-annotations</em> ::= see <a class="reference external" href="annotations.html#ref-function-annos"><em>Function Annotations</em></a> + +<em>typedef-annotations</em> ::= see <a class="reference external" href="annotations.html#ref-typedef-annos"><em>Typedef Annotations</em></a> + +<em>variable-annotations</em> ::= see <a class="reference external" href="annotations.html#ref-variable-annos"><em>Variable Annotations</em></a> + +<em>type</em> ::= [<strong>const</strong>] <em>base-type</em> {<strong>*</strong>} [<strong>&</strong>] + +<em>type-list</em> ::= <em>type</em> [<strong>,</strong> <em>type-list</em>] + +<em>base-type</em> ::= [<em>scoped-name</em> | <em>template</em> | <strong>struct</strong> <em>scoped-name</em> | + <strong>char</strong> | <strong>signed char</strong> | <strong>unsigned char</strong> | <strong>wchar_t</strong> | + <strong>int</strong> | <strong>unsigned</strong> | <strong>unsigned int</strong> | + <strong>short</strong> | <strong>unsigned short</strong> | + <strong>long</strong> | <strong>unsigned long</strong> | + <strong>long long</strong> | <strong>unsigned long long</strong> | + <strong>float</strong> | <strong>double</strong> | + <strong>bool</strong> | + <strong>void</strong> | + <a class="reference internal" href="#stype-SIP_PYCALLABLE"><tt class="xref docutils literal"><span class="pre">SIP_PYCALLABLE</span></tt></a> | + <a class="reference internal" href="#stype-SIP_PYDICT"><tt class="xref docutils literal"><span class="pre">SIP_PYDICT</span></tt></a> | + <a class="reference internal" href="#stype-SIP_PYLIST"><tt class="xref docutils literal"><span class="pre">SIP_PYLIST</span></tt></a> | + <a class="reference internal" href="#stype-SIP_PYOBJECT"><tt class="xref docutils literal"><span class="pre">SIP_PYOBJECT</span></tt></a> | + <a class="reference internal" href="#stype-SIP_PYSLICE"><tt class="xref docutils literal"><span class="pre">SIP_PYSLICE</span></tt></a> | + <a class="reference internal" href="#stype-SIP_PYTUPLE"><tt class="xref docutils literal"><span class="pre">SIP_PYTUPLE</span></tt></a> | + <a class="reference internal" href="#stype-SIP_PYTYPE"><tt class="xref docutils literal"><span class="pre">SIP_PYTYPE</span></tt></a>] + +<em>scoped-name</em> ::= <em>name</em> [<strong>::</strong> <em>scoped-name</em>] + +<em>template</em> ::= <em>scoped-name</em> <strong><</strong> <em>type-list</em> <strong>></strong> + +<em>dotted-name</em> ::= <em>name</em> [<strong>.</strong> <em>dotted-name</em>] + +<em>name</em> ::= _A-Za-z {_A-Za-z0-9} +</pre> +<p>Here is a short list of differences between C++ and the subset supported by +SIP that might trip you up.</p> +<blockquote> +<ul class="simple"> +<li>SIP does not support the use of <tt class="docutils literal"><span class="pre">[]</span></tt> in types. Use pointers instead.</li> +<li>A global <tt class="docutils literal"><span class="pre">operator</span></tt> can only be defined if its first argument is a +class or a named enum that has been wrapped in the same module.</li> +<li>Variables declared outside of a class are effectively read-only.</li> +<li>A class’s list of super-classes doesn’t not include any access specifier +(e.g. <tt class="docutils literal"><span class="pre">public</span></tt>).</li> +</ul> +</blockquote> +</div> +<div class="section" id="variable-numbers-of-arguments"> +<h2>Variable Numbers of Arguments<a class="headerlink" href="#variable-numbers-of-arguments" title="Permalink to this headline">¶</a></h2> +<p>SIP supports the use of <tt class="docutils literal"><span class="pre">...</span></tt> as the last part of a function signature. Any +remaining arguments are collected as a Python tuple.</p> +</div> +<div class="section" id="additional-sip-types"> +<h2>Additional SIP Types<a class="headerlink" href="#additional-sip-types" title="Permalink to this headline">¶</a></h2> +<p>SIP supports a number of additional data types that can be used in Python +signatures.</p> +<dl class="sip-type"> +<dt id="stype-SIP_ANYSLOT"> +<tt class="descname">SIP_ANYSLOT</tt><a class="headerlink" href="#stype-SIP_ANYSLOT" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<p>This is both a <tt class="docutils literal"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></tt> and a <tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt> that is used as the type +of the member instead of <tt class="docutils literal"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></tt> 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.</p> +<dl class="sip-type"> +<dt id="stype-SIP_PYCALLABLE"> +<tt class="descname">SIP_PYCALLABLE</tt><a class="headerlink" href="#stype-SIP_PYCALLABLE" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<p>This is a <tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt> that is a Python callable object.</p> +<dl class="sip-type"> +<dt id="stype-SIP_PYDICT"> +<tt class="descname">SIP_PYDICT</tt><a class="headerlink" href="#stype-SIP_PYDICT" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<p>This is a <tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt> that is a Python dictionary object.</p> +<dl class="sip-type"> +<dt id="stype-SIP_PYLIST"> +<tt class="descname">SIP_PYLIST</tt><a class="headerlink" href="#stype-SIP_PYLIST" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<p>This is a <tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt> that is a Python list object.</p> +<dl class="sip-type"> +<dt id="stype-SIP_PYOBJECT"> +<tt class="descname">SIP_PYOBJECT</tt><a class="headerlink" href="#stype-SIP_PYOBJECT" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<p>This is a <tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt> of any Python type.</p> +<dl class="sip-type"> +<dt id="stype-SIP_PYSLICE"> +<tt class="descname">SIP_PYSLICE</tt><a class="headerlink" href="#stype-SIP_PYSLICE" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<p>This is a <tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt> that is a Python slice object.</p> +<dl class="sip-type"> +<dt id="stype-SIP_PYTUPLE"> +<tt class="descname">SIP_PYTUPLE</tt><a class="headerlink" href="#stype-SIP_PYTUPLE" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<p>This is a <tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt> that is a Python tuple object.</p> +<dl class="sip-type"> +<dt id="stype-SIP_PYTYPE"> +<tt class="descname">SIP_PYTYPE</tt><a class="headerlink" href="#stype-SIP_PYTYPE" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<p>This is a <tt class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></tt> that is a Python type object.</p> +<dl class="sip-type"> +<dt id="stype-SIP_QOBJECT"> +<tt class="descname">SIP_QOBJECT</tt><a class="headerlink" href="#stype-SIP_QOBJECT" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<p>This is a <tt class="docutils literal"><span class="pre">QObject</span> <span class="pre">*</span></tt> that is a C++ instance of a class derived from Qt’s +<tt class="docutils literal"><span class="pre">QObject</span></tt> class.</p> +<dl class="sip-type"> +<dt id="stype-SIP_RXOBJ_CON"> +<tt class="descname">SIP_RXOBJ_CON</tt><a class="headerlink" href="#stype-SIP_RXOBJ_CON" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<p>This is a <tt class="docutils literal"><span class="pre">QObject</span> <span class="pre">*</span></tt> that is a C++ instance of a class derived from Qt’s +<tt class="docutils literal"><span class="pre">QObject</span></tt> class. It is used as the type of the receiver instead of <tt class="docutils literal"><span class="pre">const</span> +<span class="pre">QObject</span> <span class="pre">*</span></tt> in functions that implement a connection to a slot.</p> +<dl class="sip-type"> +<dt id="stype-SIP_RXOBJ_DIS"> +<tt class="descname">SIP_RXOBJ_DIS</tt><a class="headerlink" href="#stype-SIP_RXOBJ_DIS" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<p>This is a <tt class="docutils literal"><span class="pre">QObject</span> <span class="pre">*</span></tt> that is a C++ instance of a class derived from Qt’s +<tt class="docutils literal"><span class="pre">QObject</span></tt> class. It is used as the type of the receiver instead of <tt class="docutils literal"><span class="pre">const</span> +<span class="pre">QObject</span> <span class="pre">*</span></tt> in functions that implement a disconnection from a slot.</p> +<dl class="sip-type"> +<dt id="stype-SIP_SIGNAL"> +<tt class="descname">SIP_SIGNAL</tt><a class="headerlink" href="#stype-SIP_SIGNAL" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<p>This is a <tt class="docutils literal"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></tt> that is used as the type of the signal instead of +<tt class="docutils literal"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></tt> in functions that implement the connection or disconnection +of an explicitly generated signal to a slot.</p> +<dl class="sip-type"> +<dt id="stype-SIP_SLOT"> +<tt class="descname">SIP_SLOT</tt><a class="headerlink" href="#stype-SIP_SLOT" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<p>This is a <tt class="docutils literal"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></tt> that is used as the type of the member instead of +<tt class="docutils literal"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></tt> in functions that implement the connection or disconnection +of an explicitly generated signal to a slot.</p> +<dl class="sip-type"> +<dt id="stype-SIP_SLOT_CON"> +<tt class="descname">SIP_SLOT_CON</tt><a class="headerlink" href="#stype-SIP_SLOT_CON" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<p>This is a <tt class="docutils literal"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></tt> that is used as the type of the member instead of +<tt class="docutils literal"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></tt> 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.</p> +<p>To take an example, <tt class="docutils literal"><span class="pre">QAccel::connectItem()</span></tt> 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:</p> +<div class="highlight-python"><pre>bool connectItem(int id, const QObject *receiver, const char *member);</pre> +</div> +<p>The corresponding SIP specification is:</p> +<div class="highlight-python"><pre>bool connectItem(int, SIP_RXOBJ_CON, SIP_SLOT_CON(int));</pre> +</div> +<dl class="sip-type"> +<dt id="stype-SIP_SLOT_DIS"> +<tt class="descname">SIP_SLOT_DIS</tt><a class="headerlink" href="#stype-SIP_SLOT_DIS" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<p>This is a <tt class="docutils literal"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></tt> that is used as the type of the member instead of +<tt class="docutils literal"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></tt> 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.</p> +</div> +<div class="section" id="classic-division-and-true-division"> +<h2>Classic Division and True Division<a class="headerlink" href="#classic-division-and-true-division" title="Permalink to this headline">¶</a></h2> +<p>SIP supports the <tt class="docutils literal"><span class="pre">__div__</span></tt> and <tt class="docutils literal"><span class="pre">__truediv__</span></tt> special methods (and the +corresponding inplace versions) for both Python v2 and v3.</p> +<p>For Python v2 the <tt class="docutils literal"><span class="pre">__div__</span></tt> method will be used for both classic and true +division if a <tt class="docutils literal"><span class="pre">__truediv__</span></tt> method is not defined.</p> +<p>For Python v3 the <tt class="docutils literal"><span class="pre">__div__</span></tt> method will be used for true division if a +<tt class="docutils literal"><span class="pre">__truediv__</span></tt> method is not defined.</p> +<p>For all versions of Python, if both methods are defined then <tt class="docutils literal"><span class="pre">__div__</span></tt> +should be defined first.</p> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference external" href="#">SIP Specification Files</a><ul> +<li><a class="reference external" href="#syntax-definition">Syntax Definition</a></li> +<li><a class="reference external" href="#variable-numbers-of-arguments">Variable Numbers of Arguments</a></li> +<li><a class="reference external" href="#additional-sip-types">Additional SIP Types</a></li> +<li><a class="reference external" href="#classic-division-and-true-division">Classic Division and True Division</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="command_line.html" + title="previous chapter">The SIP Command Line</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="directives.html" + title="next chapter">Directives</a></p> + <div id="searchbox" style="display: none"> + <h3>Quick search</h3> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" size="18" /> + <input type="submit" value="Go" /> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </form> + <p class="searchtip" style="font-size: 90%"> + Enter search terms or a module, class or function name. + </p> + </div> + <script type="text/javascript">$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="modindex.html" title="Global Module Index" + >modules</a> |</li> + <li class="right" > + <a href="directives.html" title="Directives" + >next</a> |</li> + <li class="right" > + <a href="command_line.html" title="The SIP Command Line" + >previous</a> |</li> + <li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2010 Riverbank Computing Limited. + Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.4. + </div> + </body> +</html>
\ No newline at end of file diff --git a/doc/html/using.html b/doc/html/using.html new file mode 100644 index 0000000..5ff6786 --- /dev/null +++ b/doc/html/using.html @@ -0,0 +1,731 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + + <title>Using SIP — SIP 4.10.5 Reference Guide</title> + <link rel="stylesheet" href="_static/default.css" type="text/css" /> + <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '#', + VERSION: '4.10.5', + COLLAPSE_MODINDEX: false, + FILE_SUFFIX: '.html', + HAS_SOURCE: true + }; + </script> + <script type="text/javascript" src="_static/jquery.js"></script> + <script type="text/javascript" src="_static/doctools.js"></script> + <link rel="top" title="SIP 4.10.5 Reference Guide" href="index.html" /> + <link rel="next" title="The SIP Command Line" href="command_line.html" /> + <link rel="prev" title="Installation" href="installation.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="modindex.html" title="Global Module Index" + accesskey="M">modules</a> |</li> + <li class="right" > + <a href="command_line.html" title="The SIP Command Line" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="installation.html" title="Installation" + accesskey="P">previous</a> |</li> + <li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="using-sip"> +<span id="ref-using"></span><h1>Using SIP<a class="headerlink" href="#using-sip" title="Permalink to this headline">¶</a></h1> +<p>Bindings are generated by the SIP code generator from a number of specification +files, typically with a <tt class="docutils literal"><span class="pre">.sip</span></tt> extension. Specification files look very +similar to C and C++ header files, but often with additional information (in +the form of a <em>directive</em> or an <em>annotation</em>) and code so that the bindings +generated can be finely tuned.</p> +<div class="section" id="a-simple-c-example"> +<span id="ref-simple-c-example"></span><h2>A Simple C++ Example<a class="headerlink" href="#a-simple-c-example" title="Permalink to this headline">¶</a></h2> +<p>We start with a simple example. Let’s say you have a (fictional) C++ library +that implements a single class called <tt class="docutils literal"><span class="pre">Word</span></tt>. The class has one constructor +that takes a <tt class="docutils literal"><span class="pre">\0</span></tt> terminated character string as its single argument. The +class has one method called <tt class="docutils literal"><span class="pre">reverse()</span></tt> which takes no arguments and returns +a <tt class="docutils literal"><span class="pre">\0</span></tt> terminated character string. The interface to the class is defined in +a header file called <tt class="docutils literal"><span class="pre">word.h</span></tt> which might look something like this:</p> +<div class="highlight-python"><pre>// Define the interface to the word library. + +class Word { + const char *the_word; + +public: + Word(const char *w); + + char *reverse() const; +};</pre> +</div> +<p>The corresponding SIP specification file would then look something like this:</p> +<div class="highlight-python"><pre>// 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; +};</pre> +</div> +<p>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.</p> +<blockquote> +<ul class="simple"> +<li>The <a class="reference external" href="directives.html#directive-%Module"><tt class="xref docutils literal"><span class="pre">%Module</span></tt></a> directive has been added <a class="footnote-reference" href="#id4" id="id1">[1]</a>. This is used to +name the Python module that is being created and to give it a +<em>generation</em> number. In this example these are <tt class="docutils literal"><span class="pre">word</span></tt> and <tt class="docutils literal"><span class="pre">0</span></tt> +respectively. The generation number is effectively the version number of +the module.</li> +<li>The <a class="reference external" href="directives.html#directive-%TypeHeaderCode"><tt class="xref docutils literal"><span class="pre">%TypeHeaderCode</span></tt></a> directive has been added. The text +between this and the following <a class="reference external" href="directives.html#directive-%End"><tt class="xref docutils literal"><span class="pre">%End</span></tt></a> directive is included +literally in the code that SIP generates. Normally it is used, as in +this case, to <tt class="docutils literal"><span class="pre">#include</span></tt> the corresponding C++ (or C) header file <a class="footnote-reference" href="#id5" id="id2">[2]</a>.</li> +<li>The declaration of the private variable <tt class="docutils literal"><span class="pre">this_word</span></tt> has been removed. +SIP does not support access to either private or protected instance +variables.</li> +</ul> +</blockquote> +<p>If we want to we can now generate the C++ code in the current directory by +running the following command:</p> +<div class="highlight-python"><div class="highlight"><pre><span class="n">sip</span> <span class="o">-</span><span class="n">c</span> <span class="o">.</span> <span class="n">word</span><span class="o">.</span><span class="n">sip</span> +</pre></div> +</div> +<p>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 +<a class="reference external" href="build_system.html#ref-build-system"><em>SIP build system</em></a> to do the whole thing.</p> +<p>Using the SIP build system is simply a matter of writing a small Python script. +In this simple example we will assume that the <tt class="docutils literal"><span class="pre">word</span></tt> 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.</p> +<p>This is the simplest script (conventionally called <tt class="docutils literal"><span class="pre">configure.py</span></tt>):</p> +<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">os</span> +<span class="kn">import</span> <span class="nn">sipconfig</span> + +<span class="c"># The name of the SIP build file generated by SIP and used by the build</span> +<span class="c"># system.</span> +<span class="n">build_file</span> <span class="o">=</span> <span class="s">"word.sbf"</span> + +<span class="c"># Get the SIP configuration information.</span> +<span class="n">config</span> <span class="o">=</span> <span class="n">sipconfig</span><span class="o">.</span><span class="n">Configuration</span><span class="p">()</span> + +<span class="c"># Run SIP to generate the code.</span> +<span class="n">os</span><span class="o">.</span><span class="n">system</span><span class="p">(</span><span class="s">" "</span><span class="o">.</span><span class="n">join</span><span class="p">([</span><span class="n">config</span><span class="o">.</span><span class="n">sip_bin</span><span class="p">,</span> <span class="s">"-c"</span><span class="p">,</span> <span class="s">"."</span><span class="p">,</span> <span class="s">"-b"</span><span class="p">,</span> <span class="n">build_file</span><span class="p">,</span> <span class="s">"word.sip"</span><span class="p">]))</span> + +<span class="c"># Create the Makefile.</span> +<span class="n">makefile</span> <span class="o">=</span> <span class="n">sipconfig</span><span class="o">.</span><span class="n">SIPModuleMakefile</span><span class="p">(</span><span class="n">config</span><span class="p">,</span> <span class="n">build_file</span><span class="p">)</span> + +<span class="c"># Add the library we are wrapping. The name doesn't include any platform</span> +<span class="c"># specific prefixes or extensions (e.g. the "lib" prefix on UNIX, or the</span> +<span class="c"># ".dll" extension on Windows).</span> +<span class="n">makefile</span><span class="o">.</span><span class="n">extra_libs</span> <span class="o">=</span> <span class="p">[</span><span class="s">"word"</span><span class="p">]</span> + +<span class="c"># Generate the Makefile itself.</span> +<span class="n">makefile</span><span class="o">.</span><span class="n">generate</span><span class="p">()</span> +</pre></div> +</div> +<p>Hopefully this script is self-documenting. The key parts are the +<tt class="docutils literal"><span class="pre">Configuration</span></tt> and <tt class="docutils literal"><span class="pre">SIPModuleMakefile</span></tt> classes. The build system contains +other Makefile classes, for example to build programs or to call other +Makefiles in sub-directories.</p> +<p>After running the script (using the Python interpreter the extension module is +being created for) the generated C++ code and <tt class="docutils literal"><span class="pre">Makefile</span></tt> will be in the +current directory.</p> +<p>To compile and install the extension module, just run the following +commands <a class="footnote-reference" href="#id6" id="id3">[3]</a>:</p> +<div class="highlight-python"><pre>make +make install</pre> +</div> +<p>That’s all there is to it.</p> +<p>See <a class="reference external" href="distutils.html#ref-distutils"><em>Building Your Extension with distutils</em></a> for an example of how to build this example using +distutils.</p> +<table class="docutils footnote" frame="void" id="id4" rules="none"> +<colgroup><col class="label" /><col /></colgroup> +<tbody valign="top"> +<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>All SIP directives start with a <tt class="docutils literal"><span class="pre">%</span></tt> as the first non-whitespace +character of a line.</td></tr> +</tbody> +</table> +<table class="docutils footnote" frame="void" id="id5" rules="none"> +<colgroup><col class="label" /><col /></colgroup> +<tbody valign="top"> +<tr><td class="label"><a class="fn-backref" href="#id2">[2]</a></td><td>SIP includes many code directives like this. They differ in where the +supplied code is placed by SIP in the generated code.</td></tr> +</tbody> +</table> +<table class="docutils footnote" frame="void" id="id6" rules="none"> +<colgroup><col class="label" /><col /></colgroup> +<tbody valign="top"> +<tr><td class="label"><a class="fn-backref" href="#id3">[3]</a></td><td>On Windows you might run <tt class="docutils literal"><span class="pre">nmake</span></tt> or <tt class="docutils literal"><span class="pre">mingw32-make</span></tt> instead.</td></tr> +</tbody> +</table> +</div> +<div class="section" id="id7"> +<h2>A Simple C Example<a class="headerlink" href="#id7" title="Permalink to this headline">¶</a></h2> +<p>Let’s now look at a very similar example of wrapping a fictional C library:</p> +<div class="highlight-python"><pre>/* 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);</pre> +</div> +<p>The corresponding SIP specification file would then look something like this:</p> +<div class="highlight-python"><pre>/* 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);</pre> +</div> +<p>Again, let’s look at the differences between the two files.</p> +<blockquote> +<ul class="simple"> +<li>The <a class="reference external" href="directives.html#directive-%CModule"><tt class="xref docutils literal"><span class="pre">%CModule</span></tt></a> directive has been added. This has the same +syntax as the <a class="reference external" href="directives.html#directive-%Module"><tt class="xref docutils literal"><span class="pre">%Module</span></tt></a> directive used in the previous example +but tells SIP that the library being wrapped is implemented in C rather +than C++.</li> +<li>The <a class="reference external" href="directives.html#directive-%TypeHeaderCode"><tt class="xref docutils literal"><span class="pre">%TypeHeaderCode</span></tt></a> directive has been added.</li> +<li>The <a class="reference external" href="annotations.html#fanno-Factory"><tt class="xref docutils literal"><span class="pre">Factory</span></tt></a> annotation has been added to the <tt class="docutils literal"><span class="pre">create_word()</span></tt> +function. This tells SIP that a newly created structure is being +returned and it is owned by Python.</li> +</ul> +</blockquote> +<p>The <tt class="docutils literal"><span class="pre">configure.py</span></tt> build system script described in the previous example can +be used for this example without change.</p> +</div> +<div class="section" id="a-more-complex-c-example"> +<h2>A More Complex C++ Example<a class="headerlink" href="#a-more-complex-c-example" title="Permalink to this headline">¶</a></h2> +<p>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.</p> +<p>The library contains a single C++ class called <tt class="docutils literal"><span class="pre">Hello</span></tt> which is derived from +Qt’s <tt class="docutils literal"><span class="pre">QLabel</span></tt> class. It behaves just like <tt class="docutils literal"><span class="pre">QLabel</span></tt> except that the text +in the label is hard coded to be <tt class="docutils literal"><span class="pre">Hello</span> <span class="pre">World</span></tt>. 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 <tt class="docutils literal"><span class="pre">setDefault()</span></tt> that is not implemented +in the Windows version of the library.</p> +<p>The <tt class="docutils literal"><span class="pre">hello.h</span></tt> header file looks something like this:</p> +<div class="highlight-python"><pre>// 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</pre> +</div> +<p>The corresponding SIP specification file would then look something like this:</p> +<div class="highlight-python"><pre>// 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</pre> +</div> +<p>Again we look at the differences, but we’ll skip those that we’ve looked at in +previous examples.</p> +<blockquote> +<ul class="simple"> +<li>The <a class="reference external" href="directives.html#directive-%Import"><tt class="xref docutils literal"><span class="pre">%Import</span></tt></a> directive has been added to specify that we are +extending the class hierarchy defined in the file <tt class="docutils literal"><span class="pre">QtGui/QtGuimod.sip</span></tt>. +This file is part of PyQt. The build system will take care of finding +the file’s exact location.</li> +<li>The <a class="reference external" href="directives.html#directive-%If"><tt class="xref docutils literal"><span class="pre">%If</span></tt></a> directive has been added to specify that everything +<a class="footnote-reference" href="#id11" id="id8">[4]</a> up to the matching <a class="reference external" href="directives.html#directive-%End"><tt class="xref docutils literal"><span class="pre">%End</span></tt></a> directive only applies to Qt +v4.2 and later. <tt class="docutils literal"><span class="pre">Qt_4_2_0</span></tt> is a <em>tag</em> defined in <tt class="docutils literal"><span class="pre">QtCoremod.sip</span></tt> +<a class="footnote-reference" href="#id12" id="id9">[5]</a> using the <a class="reference external" href="directives.html#directive-%Timeline"><tt class="xref docutils literal"><span class="pre">%Timeline</span></tt></a> directive. <a class="reference external" href="directives.html#directive-%Timeline"><tt class="xref docutils literal"><span class="pre">%Timeline</span></tt></a> +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 <tt class="docutils literal"><span class="pre">configure.py</span></tt> +scripts for working out the correct tags to use according to which +version of the library is actually installed.</li> +<li>The <tt class="docutils literal"><span class="pre">public</span></tt> keyword used in defining the super-classes has been +removed. This is not supported by SIP.</li> +<li>The <a class="reference external" href="annotations.html#aanno-TransferThis"><tt class="xref docutils literal"><span class="pre">TransferThis</span></tt></a> annotation has been added to the constructor’s +argument. It specifies that if the argument is not 0 (i.e. the <tt class="docutils literal"><span class="pre">Hello</span></tt> +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 <tt class="docutils literal"><span class="pre">QObject</span></tt> 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 <a class="reference internal" href="#ref-object-ownership"><em>Ownership of Objects</em></a>. SIP provides many other +annotations that can be applied to arguments, functions and classes. +Multiple annotations are separated by commas. Annotations may have +values.</li> +<li>The <tt class="docutils literal"><span class="pre">=</span></tt> operator has been removed. This operator is not supported by +SIP.</li> +<li>The <a class="reference external" href="directives.html#directive-%If"><tt class="xref docutils literal"><span class="pre">%If</span></tt></a> directive has been added to specify that everything +up to the matching <a class="reference external" href="directives.html#directive-%End"><tt class="xref docutils literal"><span class="pre">%End</span></tt></a> directive does not apply to Windows. +<tt class="docutils literal"><span class="pre">WS_WIN</span></tt> is another tag defined by PyQt, this time using the +<a class="reference external" href="directives.html#directive-%Platforms"><tt class="xref docutils literal"><span class="pre">%Platforms</span></tt></a> directive. Tags defined by the +<a class="reference external" href="directives.html#directive-%Platforms"><tt class="xref docutils literal"><span class="pre">%Platforms</span></tt></a> directive are mutually exclusive, i.e. only one +may be valid at a time <a class="footnote-reference" href="#id13" id="id10">[6]</a>.</li> +</ul> +</blockquote> +<p>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.</p> +<p>We now look at the <tt class="docutils literal"><span class="pre">configure.py</span></tt> script. This is a little different to the +script in the previous examples for two related reasons.</p> +<p>Firstly, PyQt includes a pure Python module called <tt class="docutils literal"><span class="pre">pyqtconfig</span></tt> 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.</p> +<p>Secondly, we generate a configuration module (called <tt class="docutils literal"><span class="pre">helloconfig</span></tt>) for our +own <tt class="docutils literal"><span class="pre">hello</span></tt> 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.</p> +<p>Now we have two scripts. First the <tt class="docutils literal"><span class="pre">configure.py</span></tt> script:</p> +<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">os</span> +<span class="kn">import</span> <span class="nn">sipconfig</span> +<span class="kn">from</span> <span class="nn">PyQt4</span> <span class="kn">import</span> <span class="n">pyqtconfig</span> + +<span class="c"># The name of the SIP build file generated by SIP and used by the build</span> +<span class="c"># system.</span> +<span class="n">build_file</span> <span class="o">=</span> <span class="s">"hello.sbf"</span> + +<span class="c"># Get the PyQt configuration information.</span> +<span class="n">config</span> <span class="o">=</span> <span class="n">pyqtconfig</span><span class="o">.</span><span class="n">Configuration</span><span class="p">()</span> + +<span class="c"># Get the extra SIP flags needed by the imported PyQt modules. Note that</span> +<span class="c"># this normally only includes those flags (-x and -t) that relate to SIP's</span> +<span class="c"># versioning system.</span> +<span class="n">pyqt_sip_flags</span> <span class="o">=</span> <span class="n">config</span><span class="o">.</span><span class="n">pyqt_sip_flags</span> + +<span class="c"># Run SIP to generate the code. Note that we tell SIP where to find the qt</span> +<span class="c"># module's specification files using the -I flag.</span> +<span class="n">os</span><span class="o">.</span><span class="n">system</span><span class="p">(</span><span class="s">" "</span><span class="o">.</span><span class="n">join</span><span class="p">([</span><span class="n">config</span><span class="o">.</span><span class="n">sip_bin</span><span class="p">,</span> <span class="s">"-c"</span><span class="p">,</span> <span class="s">"."</span><span class="p">,</span> <span class="s">"-b"</span><span class="p">,</span> <span class="n">build_file</span><span class="p">,</span> <span class="s">"-I"</span><span class="p">,</span> <span class="n">config</span><span class="o">.</span><span class="n">pyqt_sip_dir</span><span class="p">,</span> <span class="n">pyqt_sip_flags</span><span class="p">,</span> <span class="s">"hello.sip"</span><span class="p">]))</span> + +<span class="c"># We are going to install the SIP specification file for this module and</span> +<span class="c"># its configuration module.</span> +<span class="n">installs</span> <span class="o">=</span> <span class="p">[]</span> + +<span class="n">installs</span><span class="o">.</span><span class="n">append</span><span class="p">([</span><span class="s">"hello.sip"</span><span class="p">,</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">config</span><span class="o">.</span><span class="n">default_sip_dir</span><span class="p">,</span> <span class="s">"hello"</span><span class="p">)])</span> + +<span class="n">installs</span><span class="o">.</span><span class="n">append</span><span class="p">([</span><span class="s">"helloconfig.py"</span><span class="p">,</span> <span class="n">config</span><span class="o">.</span><span class="n">default_mod_dir</span><span class="p">])</span> + +<span class="c"># Create the Makefile. The QtGuiModuleMakefile class provided by the</span> +<span class="c"># pyqtconfig module takes care of all the extra preprocessor, compiler and</span> +<span class="c"># linker flags needed by the Qt library.</span> +<span class="n">makefile</span> <span class="o">=</span> <span class="n">pyqtconfig</span><span class="o">.</span><span class="n">QtGuiModuleMakefile</span><span class="p">(</span> + <span class="n">configuration</span><span class="o">=</span><span class="n">config</span><span class="p">,</span> + <span class="n">build_file</span><span class="o">=</span><span class="n">build_file</span><span class="p">,</span> + <span class="n">installs</span><span class="o">=</span><span class="n">installs</span> +<span class="p">)</span> + +<span class="c"># Add the library we are wrapping. The name doesn't include any platform</span> +<span class="c"># specific prefixes or extensions (e.g. the "lib" prefix on UNIX, or the</span> +<span class="c"># ".dll" extension on Windows).</span> +<span class="n">makefile</span><span class="o">.</span><span class="n">extra_libs</span> <span class="o">=</span> <span class="p">[</span><span class="s">"hello"</span><span class="p">]</span> + +<span class="c"># Generate the Makefile itself.</span> +<span class="n">makefile</span><span class="o">.</span><span class="n">generate</span><span class="p">()</span> + +<span class="c"># Now we create the configuration module. This is done by merging a Python</span> +<span class="c"># dictionary (whose values are normally determined dynamically) with a</span> +<span class="c"># (static) template.</span> +<span class="n">content</span> <span class="o">=</span> <span class="p">{</span> + <span class="c"># Publish where the SIP specifications for this module will be</span> + <span class="c"># installed.</span> + <span class="s">"hello_sip_dir"</span><span class="p">:</span> <span class="n">config</span><span class="o">.</span><span class="n">default_sip_dir</span><span class="p">,</span> + + <span class="c"># Publish the set of SIP flags needed by this module. As these are the</span> + <span class="c"># same flags needed by the qt module we could leave it out, but this</span> + <span class="c"># allows us to change the flags at a later date without breaking</span> + <span class="c"># scripts that import the configuration module.</span> + <span class="s">"hello_sip_flags"</span><span class="p">:</span> <span class="n">pyqt_sip_flags</span> +<span class="p">}</span> + +<span class="c"># This creates the helloconfig.py module from the helloconfig.py.in</span> +<span class="c"># template and the dictionary.</span> +<span class="n">sipconfig</span><span class="o">.</span><span class="n">create_config_module</span><span class="p">(</span><span class="s">"helloconfig.py"</span><span class="p">,</span> <span class="s">"helloconfig.py.in"</span><span class="p">,</span> <span class="n">content</span><span class="p">)</span> +</pre></div> +</div> +<p>Next we have the <tt class="docutils literal"><span class="pre">helloconfig.py.in</span></tt> template script:</p> +<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">PyQt4</span> <span class="kn">import</span> <span class="n">pyqtconfig</span> + +<span class="c"># These are installation specific values created when Hello was configured.</span> +<span class="c"># The following line will be replaced when this template is used to create</span> +<span class="c"># the final configuration module.</span> +<span class="c"># @SIP_CONFIGURATION@</span> + +<span class="k">class</span> <span class="nc">Configuration</span><span class="p">(</span><span class="n">pyqtconfig</span><span class="o">.</span><span class="n">Configuration</span><span class="p">):</span> + <span class="sd">"""The class that represents Hello configuration values.</span> +<span class="sd"> """</span> + <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">sub_cfg</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span> + <span class="sd">"""Initialise an instance of the class.</span> + +<span class="sd"> sub_cfg is the list of sub-class configurations. It should be None</span> +<span class="sd"> when called normally.</span> +<span class="sd"> """</span> + <span class="c"># This is all standard code to be copied verbatim except for the</span> + <span class="c"># name of the module containing the super-class.</span> + <span class="k">if</span> <span class="n">sub_cfg</span><span class="p">:</span> + <span class="n">cfg</span> <span class="o">=</span> <span class="n">sub_cfg</span> + <span class="k">else</span><span class="p">:</span> + <span class="n">cfg</span> <span class="o">=</span> <span class="p">[]</span> + + <span class="n">cfg</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">_pkg_config</span><span class="p">)</span> + + <span class="n">pyqtconfig</span><span class="o">.</span><span class="n">Configuration</span><span class="o">.</span><span class="n">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">cfg</span><span class="p">)</span> + +<span class="k">class</span> <span class="nc">HelloModuleMakefile</span><span class="p">(</span><span class="n">pyqtconfig</span><span class="o">.</span><span class="n">QtGuiModuleMakefile</span><span class="p">):</span> + <span class="sd">"""The Makefile class for modules that %Import hello.</span> +<span class="sd"> """</span> + <span class="k">def</span> <span class="nf">finalise</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> + <span class="sd">"""Finalise the macros.</span> +<span class="sd"> """</span> + <span class="c"># Make sure our C++ library is linked.</span> + <span class="bp">self</span><span class="o">.</span><span class="n">extra_libs</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s">"hello"</span><span class="p">)</span> + + <span class="c"># Let the super-class do what it needs to.</span> + <span class="n">pyqtconfig</span><span class="o">.</span><span class="n">QtGuiModuleMakefile</span><span class="o">.</span><span class="n">finalise</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> +</pre></div> +</div> +<p>Again, we hope that the scripts are self documenting.</p> +<table class="docutils footnote" frame="void" id="id11" rules="none"> +<colgroup><col class="label" /><col /></colgroup> +<tbody valign="top"> +<tr><td class="label"><a class="fn-backref" href="#id8">[4]</a></td><td>Some parts of a SIP specification aren’t subject to version control.</td></tr> +</tbody> +</table> +<table class="docutils footnote" frame="void" id="id12" rules="none"> +<colgroup><col class="label" /><col /></colgroup> +<tbody valign="top"> +<tr><td class="label"><a class="fn-backref" href="#id9">[5]</a></td><td>Actually in <tt class="docutils literal"><span class="pre">versions.sip</span></tt>. PyQt uses the <a class="reference external" href="directives.html#directive-%Include"><tt class="xref docutils literal"><span class="pre">%Include</span></tt></a> +directive to split the SIP specification for Qt across a large number of +separate <tt class="docutils literal"><span class="pre">.sip</span></tt> files.</td></tr> +</tbody> +</table> +<table class="docutils footnote" frame="void" id="id13" rules="none"> +<colgroup><col class="label" /><col /></colgroup> +<tbody valign="top"> +<tr><td class="label"><a class="fn-backref" href="#id10">[6]</a></td><td>Tags can also be defined by the <a class="reference external" href="directives.html#directive-%Feature"><tt class="xref docutils literal"><span class="pre">%Feature</span></tt></a> directive. These +tags are not mutually exclusive, i.e. any number may be valid at a time.</td></tr> +</tbody> +</table> +</div> +<div class="section" id="ownership-of-objects"> +<span id="ref-object-ownership"></span><h2>Ownership of Objects<a class="headerlink" href="#ownership-of-objects" title="Permalink to this headline">¶</a></h2> +<p>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.</p> +<p>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.</p> +<p>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).</p> +<p>This applies equally to C structures where the structure is returned to the +heap using the <tt class="docutils literal"><span class="pre">free()</span></tt> function.</p> +<p>See also <a title="sipTransferTo" class="reference external" href="c_api.html#sipTransferTo"><tt class="xref docutils literal"><span class="pre">sipTransferTo()</span></tt></a>, <a title="sipTransferBack" class="reference external" href="c_api.html#sipTransferBack"><tt class="xref docutils literal"><span class="pre">sipTransferBack()</span></tt></a> and +<a title="sipTransferBreak" class="reference external" href="c_api.html#sipTransferBreak"><tt class="xref docutils literal"><span class="pre">sipTransferBreak()</span></tt></a>.</p> +</div> +<div class="section" id="types-and-meta-types"> +<span id="ref-types-metatypes"></span><h2>Types and Meta-types<a class="headerlink" href="#types-and-meta-types" title="Permalink to this headline">¶</a></h2> +<p>Every Python object (with the exception of the <tt class="xref docutils literal"><span class="pre">object</span></tt> 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.</p> +<p>SIP implements two super-types, <tt class="xref docutils literal"><span class="pre">sip.simplewrapper</span></tt> and +<a title="sip.wrapper" class="reference external" href="python_api.html#sip.wrapper"><tt class="xref docutils literal"><span class="pre">sip.wrapper</span></tt></a>, and a meta-type, <a title="sip.wrappertype" class="reference external" href="python_api.html#sip.wrappertype"><tt class="xref docutils literal"><span class="pre">sip.wrappertype</span></tt></a>.</p> +<p><tt class="xref docutils literal"><span class="pre">sip.simplewrapper</span></tt> is the super-type of <a title="sip.wrapper" class="reference external" href="python_api.html#sip.wrapper"><tt class="xref docutils literal"><span class="pre">sip.wrapper</span></tt></a>. The +super-type of <tt class="xref docutils literal"><span class="pre">sip.simplewrapper</span></tt> is <tt class="xref docutils literal"><span class="pre">object</span></tt>.</p> +<p><a title="sip.wrappertype" class="reference external" href="python_api.html#sip.wrappertype"><tt class="xref docutils literal"><span class="pre">sip.wrappertype</span></tt></a> is the meta-type of both <tt class="xref docutils literal"><span class="pre">sip.simplewrapper</span></tt> +and <a title="sip.wrapper" class="reference external" href="python_api.html#sip.wrapper"><tt class="xref docutils literal"><span class="pre">sip.wrapper</span></tt></a>. The super-type of <a title="sip.wrappertype" class="reference external" href="python_api.html#sip.wrappertype"><tt class="xref docutils literal"><span class="pre">sip.wrappertype</span></tt></a> is +<tt class="xref docutils literal"><span class="pre">type</span></tt>.</p> +<p><a title="sip.wrapper" class="reference external" href="python_api.html#sip.wrapper"><tt class="xref docutils literal"><span class="pre">sip.wrapper</span></tt></a> supports the concept of object ownership described in +<a class="reference internal" href="#ref-object-ownership"><em>Ownership of Objects</em></a> and, by default, is the super-type of all the types +that SIP generates.</p> +<p><tt class="xref docutils literal"><span class="pre">sip.simplewrapper</span></tt> 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.</p> +<p>SIP allows a class’s meta-type and super-type to be explicitly specified using +the <a class="reference external" href="annotations.html#canno-Metatype"><tt class="xref docutils literal"><span class="pre">Metatype</span></tt></a> and <a class="reference external" href="annotations.html#canno-Supertype"><tt class="xref docutils literal"><span class="pre">Supertype</span></tt></a> class annotations.</p> +<p>SIP also allows the default meta-type and super-type to be changed for a module +using the <a class="reference external" href="directives.html#directive-%DefaultMetatype"><tt class="xref docutils literal"><span class="pre">%DefaultMetatype</span></tt></a> and <a class="reference external" href="directives.html#directive-%DefaultSupertype"><tt class="xref docutils literal"><span class="pre">%DefaultSupertype</span></tt></a> +directives. Unlike the default super-type, the default meta-type is inherited +by importing modules.</p> +<p>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 <a title="sipRegisterPyType" class="reference external" href="c_api.html#sipRegisterPyType"><tt class="xref docutils literal"><span class="pre">sipRegisterPyType()</span></tt></a>. This is normally done in code specified +using the <a class="reference external" href="directives.html#directive-%InitialisationCode"><tt class="xref docutils literal"><span class="pre">%InitialisationCode</span></tt></a> directive.</p> +<p>As an example, PyQt4 uses <a class="reference external" href="directives.html#directive-%DefaultMetatype"><tt class="xref docutils literal"><span class="pre">%DefaultMetatype</span></tt></a> to specify a new +meta-type that handles the interaction with Qt’s own meta-type system. It also +uses <a class="reference external" href="directives.html#directive-%DefaultSupertype"><tt class="xref docutils literal"><span class="pre">%DefaultSupertype</span></tt></a> to specify that the smaller +<tt class="xref docutils literal"><span class="pre">sip.simplewrapper</span></tt> super-type is normally used. Finally it uses +<a class="reference external" href="annotations.html#canno-Supertype"><tt class="xref docutils literal"><span class="pre">Supertype</span></tt></a> as an annotation of the <tt class="docutils literal"><span class="pre">QObject</span></tt> class to override the +default and use <a title="sip.wrapper" class="reference external" href="python_api.html#sip.wrapper"><tt class="xref docutils literal"><span class="pre">sip.wrapper</span></tt></a> as the super-type so that the parent/child +relationships of <tt class="docutils literal"><span class="pre">QObject</span></tt> instances are properly maintained.</p> +</div> +<div class="section" id="lazy-type-attributes"> +<span id="ref-lazy-type-attributes"></span><h2>Lazy Type Attributes<a class="headerlink" href="#lazy-type-attributes" title="Permalink to this headline">¶</a></h2> +<p>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.</p> +<p>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 +<a title="sipRegisterAttributeGetter" class="reference external" href="c_api.html#sipRegisterAttributeGetter"><tt class="xref docutils literal"><span class="pre">sipRegisterAttributeGetter()</span></tt></a>). This will be called just before a +type’s dictionary is accessed for the first time.</p> +</div> +<div class="section" id="support-for-python-s-buffer-interface"> +<h2>Support for Python’s Buffer Interface<a class="headerlink" href="#support-for-python-s-buffer-interface" title="Permalink to this headline">¶</a></h2> +<p>SIP supports Python’s buffer interface in that whenever C/C++ requires a +<tt class="docutils literal"><span class="pre">char</span></tt> or <tt class="docutils literal"><span class="pre">char</span> <span class="pre">*</span></tt> type then any Python type that supports the buffer +interface (including ordinary Python strings) can be used.</p> +<p>If a buffer is made up of a number of segments then all but the first will be +ignored.</p> +</div> +<div class="section" id="support-for-wide-characters"> +<h2>Support for Wide Characters<a class="headerlink" href="#support-for-wide-characters" title="Permalink to this headline">¶</a></h2> +<p>SIP v4.6 introduced support for wide characters (i.e. the <tt class="docutils literal"><span class="pre">wchar_t</span></tt> 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 <a title="sipMalloc" class="reference external" href="c_api.html#sipMalloc"><tt class="xref docutils literal"><span class="pre">sipMalloc()</span></tt></a>). This then raises the problem of how this memory +is subsequently freed.</p> +<p>The following describes how SIP handles this memory in the different situations +where this is an issue.</p> +<blockquote> +<ul class="simple"> +<li>When a wide string or array is passed to a function or method then the +memory is freed (using <a title="sipFree" class="reference external" href="c_api.html#sipFree"><tt class="xref docutils literal"><span class="pre">sipFree()</span></tt></a>) after than function or method +returns.</li> +<li>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.</li> +<li>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.</li> +</ul> +</blockquote> +</div> +<div class="section" id="the-python-global-interpreter-lock"> +<span id="ref-gil"></span><h2>The Python Global Interpreter Lock<a class="headerlink" href="#the-python-global-interpreter-lock" title="Permalink to this headline">¶</a></h2> +<p>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.</p> +<p>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 <a class="reference external" href="annotations.html#fanno-ReleaseGIL"><tt class="xref docutils literal"><span class="pre">ReleaseGIL</span></tt></a> annotation can be used to +override this behaviour when required.</p> +<p>If SIP is given the <a class="reference external" href="command_line.html#cmdoption-sip-g"><em class="xref">-g</em></a> 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 <a class="reference external" href="annotations.html#fanno-HoldGIL"><tt class="xref docutils literal"><span class="pre">HoldGIL</span></tt></a> annotation can be used to +override this behaviour when required.</p> +</div> +<div class="section" id="managing-incompatible-apis"> +<span id="ref-incompat-apis"></span><h2>Managing Incompatible APIs<a class="headerlink" href="#managing-incompatible-apis" title="Permalink to this headline">¶</a></h2> +<p> +<span class="versionmodified">New in version 4.9.</span></p> +<p>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.</p> +<p>SIP’s <a class="reference external" href="directives.html#directive-%Feature"><tt class="xref docutils literal"><span class="pre">%Feature</span></tt></a> 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.</p> +<p>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.</p> +<p>This support is implemented in three parts.</p> +<p>Firstly the <a class="reference external" href="directives.html#directive-%API"><tt class="xref docutils literal"><span class="pre">%API</span></tt></a> 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.</p> +<p>Secondly the <a class="reference external" href="annotations.html#canno-API"><tt class="xref docutils literal"><span class="pre">API</span> <span class="pre">class</span></tt></a>, <a class="reference external" href="annotations.html#manno-API"><tt class="xref docutils literal"><span class="pre">mapped</span> <span class="pre">type</span></tt></a> or +<a class="reference external" href="annotations.html#fanno-API"><tt class="xref docutils literal"><span class="pre">function</span></tt></a> 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.</p> +<p>Finally the application calls <a title="sip.setapi" class="reference external" href="python_api.html#sip.setapi"><tt class="xref docutils literal"><span class="pre">sip.setapi()</span></tt></a> 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.</p> +<p>Note this mechanism is not intended as a way or providing equally valid +alternative APIs. For example:</p> +<div class="highlight-python"><pre>%API MyAPI 1 + +class Foo +{ +public: + void bar(); +}; + +class Baz : Foo +{ +public: + void bar() /API=MyAPI:2-/; +};</pre> +</div> +<p>If the following Python code is executed then an exception will be raised:</p> +<div class="highlight-python"><div class="highlight"><pre><span class="n">b</span> <span class="o">=</span> <span class="n">Baz</span><span class="p">()</span> +<span class="n">b</span><span class="o">.</span><span class="n">bar</span><span class="p">()</span> +</pre></div> +</div> +<p>This is because when version 1 of the <em>MyAPI</em> API (the default) is enabled +there is no <em>Baz.bar()</em> implementation and <em>Foo.bar()</em> will not be called +instead as might be expected.</p> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference external" href="#">Using SIP</a><ul> +<li><a class="reference external" href="#a-simple-c-example">A Simple C++ Example</a></li> +<li><a class="reference external" href="#id7">A Simple C Example</a></li> +<li><a class="reference external" href="#a-more-complex-c-example">A More Complex C++ Example</a></li> +<li><a class="reference external" href="#ownership-of-objects">Ownership of Objects</a></li> +<li><a class="reference external" href="#types-and-meta-types">Types and Meta-types</a></li> +<li><a class="reference external" href="#lazy-type-attributes">Lazy Type Attributes</a></li> +<li><a class="reference external" href="#support-for-python-s-buffer-interface">Support for Python’s Buffer Interface</a></li> +<li><a class="reference external" href="#support-for-wide-characters">Support for Wide Characters</a></li> +<li><a class="reference external" href="#the-python-global-interpreter-lock">The Python Global Interpreter Lock</a></li> +<li><a class="reference external" href="#managing-incompatible-apis">Managing Incompatible APIs</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="installation.html" + title="previous chapter">Installation</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="command_line.html" + title="next chapter">The SIP Command Line</a></p> + <div id="searchbox" style="display: none"> + <h3>Quick search</h3> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" size="18" /> + <input type="submit" value="Go" /> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </form> + <p class="searchtip" style="font-size: 90%"> + Enter search terms or a module, class or function name. + </p> + </div> + <script type="text/javascript">$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="modindex.html" title="Global Module Index" + >modules</a> |</li> + <li class="right" > + <a href="command_line.html" title="The SIP Command Line" + >next</a> |</li> + <li class="right" > + <a href="installation.html" title="Installation" + >previous</a> |</li> + <li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2010 Riverbank Computing Limited. + Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.4. + </div> + </body> +</html>
\ No newline at end of file |
