Mapped Types and Substitutions

Since Qt and KDE are C++ libraries, some of the data types and structures do not map directly to Python data types and structures. For example, Python has no 'bool' type, nor will sip (used at run time and to generate Python bindings) support C++ templates at present.

In general, every effort has been made to map the C++ types from Qt/KDE to PyQt/PyKDE. So for example, QMultiLineEdit.text () and KEdit.text () both return a QString NOT a Python string. You can convert QString to a Python string using the 'str' function, like this:

# s is a Python string
s = str (KEdit.text ())
#or
s = str (KEdit.text ().latin1 ())

In some cases, the documentation will note that a KDE method takes or returns a Python list or Python tuple. A Python list is used when the C++ type was a QList<> variant or an array (like char **). The list is a list of whatever type the C++ list or array held, so QList<int> is replaced by a Python list of type int. Similarly, QMap<QString, SomeObj> would be implemented as a Python dictionary of SomeObj whose keys are QStrings (not Python strings).

Python tuples are used to stand in for C++ structures/techniques in two ways. First, objects of the C++ struct type (when not instantiated as a class); second, when the C++ method uses a reference or pointer in the argument list to return a value (regardless of whether the method has a return type or returns void). For example, the C++ method

QString foo (int arg1, int& arg2);

would (normally) take a single argument (the arg1 value) and return a Python tuple of (QString, int), where the int in the tuple is the arg2 return value. In methods that have a return value, the first element of the tuple is the method's return value, and the remaining elements are from the argument list, in the same order in which they appear in the argument list.

There are two methods for converting C++ types to Python types: member code and mapped types. If member code is used, there is no new name given to the C++ type, but these docs will indicate the Python type to be passed or returned. If mapped types are used, the C++ type will be given a new name. The mapped type, however is not a new class that can be instantiated. It simply specifies a set of mappings to use when converting an argument or return value to C++ from Python and from Python to C++. For example, in some class named 'bar'

class bar {
...
QList<double> foo (int arg1, int arg2);
...
};

might be replaced by the mapped type DoubleList

DoubleList foo (int arg1, int arg2);

in the sip file. DoubleList itself may appear in the .sip file (a description file used to generate bindings), and in the docs, but the documentation for 'foo' may simply state that 'foo' returns a Python list. The documentation may also refer to a mapped type and point to DoubleList for an explanation of the mapped type. While methods of the type bar.foo (a, b) will exist, the type bar.DoubleList does NOT exist and can't be used in Python programs. This is true for C++ structs as well as lists, dictionaries, etc.

C++ structs can also be handled in two different ways [1]. A C++ struct is identical to a C++ class, except that it's default access class is 'public' (classes default to 'private'). Some C++ structs are implemented as classes, and will appear in the documentation that way. So the C++ struct 'foo':

struct foo
{
   int bar;
   char baz;
}

if bound as a class can be accessed as 'foo', and its members are 'foo.bar' and 'foo.baz' in Python. The second way to handle a C++ struct is using a mapped type or member code. In that case, the struct cannot be instantiated in Python, and will be manipulated in Python as a tuple. The order of the elements in the tuple will be the same as in the struct in the Qt/KDE header file, which is the same order shown in the Qt/KDE documentation.

If the argument or return type isn't clear, feel free to post a question on the PyKDE mailing list. We'll try to answer your question promptly, and hopefully improve these docs for the next release. The general conversions are:

C++ type <--> Python type

bool   <--> int
(also bool* or bool&)

QList  <--> list

QMap   <--> dictionary
QDict  <--> dictionary

struct <--> tuple or class (see docs)

char** <--> list

object**  <--> list

From the Python programmer's point of view, code will be clearer if structs were all implemented as Python classes. PyKDE is moving in that direction, but for various reasons it isn't always possible to implement a struct as a class at present.