[PyKDE] sipParseArgs

[John J. Lee]

Given the lack of documentation for sip, here is a list of format
characters for sipParseArgs as of sip 3.0, as far as I understand them
(poorly).  The other versions of this list I've seen were out of date.

Questions:

1. What is the 'func' C arg for ('y' and 'q' format characters)?

2. Why does PyQt's QValidator::validate() use the 'm' format character
 to get the C++ this, rather than t?  According to my copy of the Qt
 docs, this method is not static.

3. I don't understand the code for 'G' and 'S'


sipParseArgs format characters

fmt   Python arg             C args
|     (means: args after this one are optional)
-, I  (deprecated)
v     Python object          void **[OUT]
                              (if Python arg is None, will be NULL)
d     Float                  double *[OUT]
f     Float                  float *[OUT]
l     Integer                long *[OUT]
h     Integer                short *[OUT]
i     Integer                int *[OUT]
C     Constrained integer    int *[OUT]
                              (Python arg must lie in C int range)
c     Character              char *[OUT]
a     String byte array      char **array[OUT], int *size[OUT]
       or None
Y     Python slot to         char *sig, const void **rx, char **slot
       disconnect
y     Python slot to         void *func, char *sig, const void **rx, char **slot
       connect
Q     Qt receiver to         char *sig, void **rx, char **slot
       disconnect
q     Qt receiver to         void *func, char *sig, const void **rx, char **slot
       connect
F     Python callable        PyObject **[OUT]
R     Subclass of QObject    PyObject **[OUT]
T     Python object of       PyTypeObject *[IN], PyObject **[OUT]
       given type
N     Python object of       PyTypeObject *[IN], PyObject **[OUT]
       given type or None
O     Python object          PyObject **[OUT]
M     Class instance with    convfunc func, void *ptr[OUT], int *heap[OUT]
       convertors or None
J     Class instance with    PyObject *class[IN], void **[OUT]
       no convertors or None  (Python arg must be a subclass of C class arg)
G     Signal name            char **sig_name[OUT]
                              (Python arg must start with "2" or "9" -- why??)
S     Slot name              char **slot_name[OUT]
                              (Python arg must start with "1", "2" or "9")
s     String or None         char **[OUT]
t     self (C++ this)        sipThisType this[IN], PyObject *classObj[IN], void **sipThis[OUT]
m     self (C++ this of      sipThisType this[IN], PyObject *classObj[IN], void **sipThis[OUT]
       public class method)
p     self (C++ this of      sipThisType this[IN], PyObject *classObj[IN], void **sipThis[OUT]
       protected class method)

notes:

typedef int (*convfunc)(PyObject *, void *, int *)

Passing NULL as third argument to the convertor function tells it not
to do any conversion, but simply to check the type.

Convertor functions for the 'M' format character get called twice:
first as (*func)(python_arg, ptr, NULL) (returning true if the type of
python_arg is OK); then as int heap = (*func)(python_arg, ptr,
&is_err) (where is_err indicates success of conversion to appropriate
type, and heap is true if *ptr is on the free store and should be
delete-ed).  The second character of the format is a set of flags:

  bit   meaning
   0    If ptr is NULL, report it (calls BadNone)
   1    Transfer ownership of Python arg to C++ (calls sipTransferSelf(arg, 1))
   2    Transfer ownership of C++ arg to Python (calls sipTransferSelf(arg, 0))

The 'J' format character also uses these flags.


John