1.1License

Like Qt v4, PyQt is licensed on all platforms under a commercial license, the

GPL v2 and the GPL v3. Your PyQt license must be compatible with your Qt

license. If you use the GPL versions then your own code must also use a

You can purchase a commercial PyQt license here.

1.2PyQt Components

PyQt comprises a number of different components. First of all there are a

module. This contains the core non-GUI classes, including

the event loop and Qts signal and slot mechanism. It also includes

platform independent abstractions for Unicode, threads, mapped files,

module. This contains classes for creating and viewing

module. This module contains classes for writing UDP

and TCP clients and servers. It includes classes that implement FTP and

module. This module contains classes that enable the

module. This module contains classes that enable PyQt

module. This module contains classes that integrate with

SQL databases. It includes editable data models for database tables that

can be used with GUI classes. It also includes an implementation of

module. This module contains classes for displaying the

module. This module contains functions that enable unit

testing of PyQt applications. (PyQt does not implement the complete Qt

unit test framework. Instead it assumes that the standard Python unit

test framework will be used and implements those functions that simulate

module. This module implements a web browser engine

module. This module contains classes that implement SAX

module. This module contains classes that

module. This module contains classes that

implement a cross-platform multimedia framework that enables the use of

module. This module contains classes that allow Qt

Assistant to be integrated with a PyQt application to provide online

module. This module contains classes that allow Qt

Designer to be extended using PyQt. See Writing Qt Designer Plugins

module. This module contains classes that allow

access to ActiveX controls and COM objects. It is only available in the

module. This module consolidates the classes contained in all

of the modules described above into a single module. This has the

advantage that you dont have to worry about which underlying module

contains a particular class. It has the disadvantage that it loads the

whole of the Qt framework, thereby increasing the memory footprint of an

application. Whether you use this consolidated module, or the individual

component modules is down to personal taste. The DBus support

. PyQt does not support Qts

native DBus classes (which are very C++ orientated). Instead the

module provides support for the Qt event loop in the

included with the standard

bindings package provides support for the GLib event

loop. The API is described in The DBus Support Module. It is only

v0.80 (or

module. This module contains classes for handling the

files created by Qt Designer that describe the whole or part of a

file

and render it directly, and classes that generate Python code from a

file for later execution. It is covered in detail in The uic

module is an extention of the SIP build system and is

created when PyQt is configured. It encapsulates all the necessary

information about your Qt installation and makes it easier to write

installation scripts for bindings built on top of PyQt. It is covered

PyQt also contains a number of utility programs.

utility. It converts GUIs

created using Qt Designer to Python code. It is covered in detail in

utility. It embeds arbitrary

resources (eg. icons, images, translation files) described by a resource

collection file in a Python module. It is covered in detail in

pyrcc4. (Note It will only be included if your copy of Qt includes

utility. It extracts

all of the translatable strings from Python code and creates or updates

translation files. These are then used by Qt Linguist to manage

the translation of those strings. It is covered in detail in

pylupdate4. (Note It will only be included if your copy of Qt

When PyQt is configured a file called PyQt4.api

is generated. This can be

used by the QScintilla editor component (at

http://www.riverbankcomputing.com/software/qscintilla/) to enable the use of

auto-completion and call tips when editing PyQt code. The API file is

PyQt includes a large number of examples. These are ports to Python of many

Finally, PyQt contains the .sip

files used by SIP to generate PyQt

itself. These can be used by developers of bindings of other Qt based class

2.1Downloading SIP

SIP must be installed before building and using PyQt. You can get the latest

release of the SIP source code from

The SIP documentation can be found at

2.2Downloading PyQt

You can get the latest release of the GPL version of the PyQt source code from

If you are using the commercial version of PyQt then you should use the

download instructions which were sent to you when you made your purchase. You

2.3Configuring PyQt

After unpacking the source package (either a .tar.gz or a .zip

file

files

If you are using the commercial version of PyQt then you must copy your

You need to make sure your environment variables are set properly for your

development environment. For example, if you are using a binary distribution

file. For

directory is

Next you need to configure SIP by executing the configure.py

script. For

This assumes that the Python interpreter is on your path. Something like the

If you have multiple versions of Python installed then make sure you use the

The full set of command line options is:

The PyQt modules will be built as static libraries. This is useful when

building a custom interpreter with the PyQt modules built in to the

The generated PyQt modules contain additional tracing code that is enabled

The PyQt modules will be built with debugging symbols. On Windows this

Compiler commands and any output issued during configuration is displayed

is having

The C++ source files for a Python module will be concatenated. This

results in significantly reduced compilation times. Most, but not all,

C++ compilers can handle the large files that result. It is recommended

that you use this option if you are using GCC v3.x or MSVC v7.x. See also

option is used to concatenate the C++ source files

module) is linked against

which is linked against all the required Qt libraries and the other modules

are stub modules that populate their module dictionaries from this one.

This is useful when linking against static Qt libraries to eliminate the

need to distribute the Qt libraries while minimising the memory footprint

Normally checks for all PyQt4 modules are enabled and are built if the

corresponding Qt library can be found. Using this option only those

modules specifically enabled will be checked for and built. The option may

will be linked with the appropriate PyQt module. The option may be

program is used to determine how your Qt installation is

. This option can

to use. This option

header file of the dbus-python package can be found

utilities will be installed

. The

directory. If you

environment variable must include

The Qt Designer plugin that manages plugins implemented in Python will be

files for the PyQt modules will be installed in the directory

The checking of signed Python interpreters using the VendorID package is

The header file of the VendorID package can be found in the directory

QScintilla API file is installed even if QScintilla does

not appear to be installed. This option is implied if the

QScintilla API file is not installed even if QScintilla

subdirectory of

2.4Building PyQt

The next step is to build PyQt by running your platforms make

command.

The final step is to install PyQt by running the following command:

(Depending on your system you may require root or administrator privileges.)

This will install the various PyQt components.

3.1PyQt Signals and Qt Signals

Qt signals are statically defined as part of a C++ class. They are referenced

function. This method takes a single string

The returned value is normally passed to the QtCore.QObject.connect() method.

PyQt allows new signals to be defined dynamically. The act of emitting a

PyQt signal implicitly defines it. PyQt v4 signals are also referenced using

3.2The PyQt_PyObject Signal Argument Type

It is possible to pass any Python object as a signal argument by specifying

While this would normally be used for passing objects like lists and

dictionaries as signal arguments, it can be used for any Python type. Its

advantage when passing, for example, an integer is that the normal conversions

The reference count of the object being passed is maintained automatically.

There is no need for the emitter of a signal to keep a reference to the object

3.3Short-circuit Signals

There is also a special form of a PyQt v4 signal known as a short-circuit

signal. Short-circut signals implicitly declare each argument as being of

Short-circuit signals do not have a list of arguments or the surrounding

Short-circuit signals may only be connected to slots that have been implemented

in Python. They cannot be connected to Qt slots or the Python callables that

3.4PyQt Slots and Qt Slots

Qt slots are statically defined as part of a C++ class. They are referenced

function. This method takes a single string

The returned value is normally passed to the QtCore.QObject.connect() method.

PyQt allows any Python callable to be used as a slot, not just Qt slots. This

is done by simply referencing the callable. Because Qt slots are implemented

as class methods they are also available as Python callables. Therefore it is

for Qt slots. However, doing so

Qt allows a signal to be connected to a slot that requires fewer arguments than

the signal passes. The extra arguments are quietly discarded. PyQt slots can

Note that when a slot is a Python callable its reference count is not

increased. This means that a class instance can be deleted without having to

explicitly disconnect any signals connected to its methods. However, if a slot

is a lambda function or a partial function then its reference count is

automatically incremented to prevent it from being immediately garbage

3.5Connecting Signals and Slots

Connections between signals and slots (and other signals) are made using the

Disconnecting signals works in exactly the same way using the

method. However, not all the variations of

that method are supported by PyQt. Signals must be disconnected one at a

3.6Emitting Signals

Any instance of a class that is derived from the QtCore.QObject

class can

method. This takes a minimum of one

argument which is the signal. Any other arguments are passed to the connected

3.7The QtCore.pyqtSignature() Decorator

Many of Qts features make use of its meta-object system. In order to make

use of these features from Python it is sometimes necessary to make certain

sub-classes, properties and methods) appear

as C++ objects. In particular it is sometimes necessary to define a C++

function signature that a Python method emulates. PyQt provides the

The decorator takes a signature argument and an optional result argument. Both are strings.

The signature

is a comma separated list of C++ types representing each of

. The list may also be

must also

be given. If the name is omitted then the name of the Python method being

The result

argument is simply the C++ type of the result. If it is omitted

For example:

Any method of a class that is a sub-class of QObject

that is decorated is

The following sections describe the situations that the decorator might be

8.1Using the Generated Code

The code that is generated has an identical structure to that generated by Qts

The code is structured as a single class that is derived from the Python

type. The name of the class is the name of the toplevel object set

prepended. (In the C++ version the class is defined

The class contains a method called setupUi()

. This takes a single argument

which is the widget in which the user interface is created. The type of this

) is set in

In the following examples we assume that a .ui

file has been created

.

We also assume that the name of the file containing the generated Python code

. The generated code can then be used in a number of

The first example shows the direct approach where we simply create a simple

The second example shows the single inheritance approach where we sub-class

The third example shows the multiple inheritance approach:

It is also possible to use the same approach used in PyQt v3. This is shown in

For a full description see the Qt Designer Manual in the Qt Documentation.

8.2The uic Module

The uic module contains the following functions.

This function generates the Python code that will create a user interface

uifile is a file name or file-like object containing the .ui file.

pyfile

is the file-like object to which the generated Python code will

execute

is optionally set if a small amount of additional code is to be

generated that will display the user interface if the code is run as a

indent

is the optional number of spaces used for indentation in the

pyqt3_wrapper

is optionally set if a small wrapper is to be generated

This function loads a Qt Designer .ui

file and returns a tuple of the

generated form class and the Qt base class. These can then be used to

create any number of instances of the user interface without having to

uifile is a file name or file-like object containing the .ui file.

This function loads a Qt Designer .ui

file and returns an instance of

uifile is a file name or file-like object containing the .ui file.

baseinstance

is an optional instance of the Qt base class. If

specified then the user interface is created in it. Otherwise a new

8.3pyuic4

The pyuic4 utility is a command line interface to the uic

module. The

The full set of command line options is:

The Python code is generated using an indentation of N

spaces. If N is 0 then a tab is used. The default is

The GUI is created dynamically and displayed. No

The generated Python code includes a small wrapper that

allows the GUI to be used in the same way as it is used

The generated Python code includes a small amount of

additional code that creates and displays the GUI when

8.4Writing Qt Designer Plugins

Qt Designer can be extended by writing plugins. Normally this is done using

C++ but PyQt also allows you to write plugins in Python. Most of the time a

plugin is used to expose a custom widget to Designer so that it appears in

Designers widget box just like any other widget. It is possibe to change the

It is also possible to add new functionality to Designer. See the Qt

documentation for the full details. Here we will concentrate on describing

The process of integrating Python custom widgets with Designer is very similar

to that used with widget written using C++. However, there are particular

Designer needs to have a C++ plugin that conforms to the interface

class. (If the plugin

exposes more than one custom widget then it must conform to the

as well

as the interface class. PyQt does not allow Python classes to be

sub-classed from more than one Qt class. Designer can only connect Qt signals and slots. It has no understanding

of Python signals or callables. Designer can only edit Qt properties that represent C++ types. It has no

PyQt provides the following components and features to resolve these issues as

PyQts QtDesigner module includes additional classes (all of which have a

prefix) that are already sub-classed from the necessary Qt

classes. This avoids the need to sub-class from more than one Qt class

in Python. For example, where a C++ custom widget plugin would sub-class

, a Python custom

widget plugin would instead sub-class from

PyQt installs a C++ plugin in Designers plugin directory. It conforms

to the interface defined by the

class. It searches a

configurable set of directories looking for Python plugins that

.

Each class that is found is instantiated and the instance created is

The PYQTDESIGNERPATH

environment variable specifies the set of

directories to search for plugins. Directory names are separated by a

path separator (a semi-colon on Windows and a colon on other platforms).

If a directory name is empty (ie. there are consecutive path separators

or a leading or trailing path separator) then a set of default

directories is automatically inserted at that point. The default

subdirectory of each directory that

Designer searches for its own plugins. If the environment variable is

not set then only the default directories are searched. If a files

A Python custom widget may define new Qt signals using the

class attribute. This should define a sequence of

strings each of which is the C++ signature (but excluding the return

A Python class method may be defined as a new Qt slot by using the

A new Qt property may be defined using the QtCore.pyqtProperty()

function. It is used in the same way as the standard Python

function. In fact, Qt properties defined in this way

also behave as Python properties. The full signature of the function is

type

is a string that defines the C++ type of the property.

is a function used to reset the value of the property to its

default value.

sets the Qt DESIGNABLE flag.

sets the Qt SCRIPTABLE flag.

sets the Qt STORED flag.

The remaining arguments are the same as those used by the standard

Qt makes no use of the fdel

function and Python makes no use of the

Note that the ability to define new Qt signals, slots and properties from

Python is potentially useful to plugins conforming to any plugin interface and

For a simple but complete and fully documented example of a custom widget that

defines new Qt signals, slots and properties, and its plugin, look in the

directory of the PyQt source package. The

custom widget and the

9.1pyrcc4

pyrcc4 is PyQts equivalent to Qts rcc

utility and is used in exactly

file, and the resource files, and

ed by the

application in order for those resources to be made available just as if they

pyrcc4 will only be included if your copy of Qt includes the XML module.

10.1pylupdate4

pylupdate4 is PyQts equivalent to Qts lupdate

utility and is used in

project file is read that specifies the

Python source files and Qt Designer interface files from which the text that

file also specifies the

updates (or creates if necessary)

pylupdate4 will only be included if your copy of Qt includes the XML module.

10.2Differences Between PyQt and Qt

Qt implements internationalisation support through the QTranslator

class,

and

method is used to obtain

the correct translation of a message. The translation process uses a message

is

and uses the hardcoded class name as the context.

allows the context to be

Unfortunately, because of the way Qt implements tr() (and trUtf8()

) it

is not possible for PyQt to exactly reproduce its behaviour. The PyQt

) uses the class name of the

instance as the context. The key difference, and the source of potential

problems, is that the context is determined dynamically in PyQt, but is

hardcoded in Qt. In other words, the context of a translation may change

In the above the message is translated by a.hello()

using a context of

. In the equivalent C++

The PyQt behaviour is unsatisfactory and may be changed in the future. It is

be used in preference to

). This is guaranteed to work with current and

future versions of PyQt and makes it much easier to share message files

12.1Python Strings, Qt Strings and Unicode

Unicode support was added to Qt in v2.0 and to Python in v1.6. In Qt, Unicode

class. It is important to

instances, Python string objects and Python Unicode

objects are all different but conversions between them are automatic in almost

Whenever PyQt expects a QString

as a function argument, a Python string

object or a Python Unicode object can be provided instead, and PyQt will do

You may also manually convert Python string and Unicode objects to QString instances by using the QString

constructor as demonstrated in the following

In order to convert a QString

to a Python string object use the Python

and an empty

In order to convert a QString

to a Python Unicode object use the Python

and an

QString

also implements Pythons buffer protocol which means that a

can be used in many places where a Python string or Unicode object

12.2Garbage Collection

C++ does not garbage collect unreferenced class instances, whereas Python does.

In the following C++ fragment both colours exist even though the first can no

In the corresponding Python fragment, the first colour is destroyed when the

In Python, each colour must be assigned to different names. Typically this is

Sometimes a Qt class instance will maintain a pointer to another instance and

will eventually call the destructor of that second instance. The most common

(and any of its sub-classes) keeps pointers to

its children and will automatically call their destructors. In these cases,

the corresponding Python object will also keep a reference to the corresponding

So, in the following Python fragment, the first QLabel

is not destroyed

still has

12.3Multiple Inheritance

It is not possible to define a new Python class that sub-classes from more than

12.4Access to Protected Member Functions

When an instance of a C++ class is not created from Python it is not possible

to access the protected member functions, or emit any signals, of that

instance. Attempts to do so will raise a Python exception. Also, any Python

methods corresponding to the instances virtual member functions will never be

12.5None and NULL

Throughout PyQt, the None value can be specified wherever NULL

is

Equally, NULL is converted to None

whenever it is returned by the

12.6Support for void *

PyQt (actually SIP) represents void *

values as objects of type

. Such values are often used to pass the addresses of external

objects between different Python modules. To make this easier, a Python

integer (or anything that Python can convert to an integer) can be used

A sip.voidptr may be converted to a Python integer by using the int() builtin function.

A sip.voidptr

may be converted to a Python string by using its

method takes an optional integer

A sip.voidptr

may also be given a size (ie. the size of the block of

method. If it has a

size then it is also able to support Pythons buffer protocol. This means

builtin to create an object

that treats the block of memory as a mutable list of bytes. It also means

module can be used to unpack and pack binary data

12.7super and PyQt Classes

Internally PyQt implements a lazy technique for attribute lookup where

attributes are only placed in type and instance dictionaries when they are

first referenced. This technique is needed to reduce the time taken to import

In most circumstances this technique is transparent to an application. The

is currently implemented means that the lazy lookup is bypassed resulting in

exceptions unless the attribute has been previously

Note that this restriction applies to any class wrapped by SIP and not just

14.1pyqtconfig Classes

This class encapsulates configuration values that can be accessed as

The following configuration values are provided in addition to those

when PyQt was

Python package is

files are

files are installed in a

command line arguments used

to build the PyQt modules. These should also be used when

any PyQt modules. pyqt_version The PyQt version as a 3 part hexadecimal number (e.g. v4.0.1 is

). pyqt_version_str The PyQt version as a string. For development snapshots it will

for the Qt

installation. qt_dir The root directory of the Qt installation (normally the directory

for the Qt

for the Qt

installation. qt_threaded Set if Qt is built with thread support (always set for PyQt). qt_version The Qt version as a 3 part hexadecimal number (e.g. v4.1.2 is

Initialise the instance.

sub_cfg

is an optional list of sub-class configurations. It should

method of a sub-class to append its

own dictionary of configuration values before passing the list to its

QtAssistantModuleMakefile(QtNetworkModuleMakefile) This class encapsulates a Makefile to build a SIP generated Python

module. QAxContainerModuleMakefile(QtGuiModuleMakefile) This class encapsulates a Makefile to build a SIP generated Python

module. QtCoreModuleMakefile(sipconfig.SIPModuleMakefile) This class encapsulates a Makefile to build a SIP generated Python

module. QtHelpModuleMakefile(QtGuiModuleMakefile) This class encapsulates a Makefile to build a SIP generated Python

module. QtGuiModuleMakefile(QtCoreModuleMakefile) This class encapsulates a Makefile to build a SIP generated Python

module. QtNetworkModuleMakefile(QtCoreModuleMakefile) This class encapsulates a Makefile to build a SIP generated Python

module. QtOpenGLModuleMakefile(QtGuiModuleMakefile) This class encapsulates a Makefile to build a SIP generated Python

module. QtScriptModuleMakefile(QtCoreModuleMakefile) This class encapsulates a Makefile to build a SIP generated Python

module. QtSqlModuleMakefile(QtGuiModuleMakefile) This class encapsulates a Makefile to build a SIP generated Python

module. QtSvgModuleMakefile(QtGuiModuleMakefile) This class encapsulates a Makefile to build a SIP generated Python

module. QtTestModuleMakefile(QtCoreModuleMakefile) This class encapsulates a Makefile to build a SIP generated Python

module. QtWebKitModuleMakefile(QtNetworkModuleMakefile) This class encapsulates a Makefile to build a SIP generated Python

module. QtXmlModuleMakefile(QtCoreModuleMakefile) This class encapsulates a Makefile to build a SIP generated Python

module. QtXmlPatternsModuleMakefile(QtCoreModuleMakefile) This class encapsulates a Makefile to build a SIP generated Python

module. phononModuleMakefile(QtGuiModuleMakefile) This class encapsulates a Makefile to build a SIP generated Python