This is a list of Frequently Asked Questions about PySide binding and the generation system used to create it. Feel free to suggest new entries!
Project
What is PySide?
PySide is an open source software project providing Python bindings for the Qt framework.
Why develop new Qt Python bindings?
We researched existing options in the market, but due to our licensing and technical requirements, we decided that building our own bindings was the best option for us.
What about PyQt?
Nokia’s initial research into Python bindings for Qt involved speaking with Riverbank Computing, the makers of PyQt. We had several discussions with them to see if it was possible to use PyQt to achieve our goals. Unfortunately, a common agreement could not be found , so in the end we decided to proceed with PySide.
We will however maintain API compatibility with PyQt (you can use the same method names but can’t inter-operate with PyQt), at least for the initial release. To import PySide you have to use “import PySide” instead of “import PyQt4″.
What is the role of Nokia?
Work on PySide was initiated within the Maemo division of Nokia once the lack of suitably licensed Qt Python bindings became apparent. To encourage Qt application development on Python, the project was decided to be made available for the developer community under a permissive license.
Will PySide be open for community involvement?
Absolutely! While we plan on continuing to develop PySide, we are aware that it will be most successful if we can have additional community members joining in on the development and testing. PySide community resources can be found at this website.
Nokia provides developers for the project and will be initially leading it. That doesn’t say Nokia wouldn’t want to closely co-operate with the developer community, however!
Bindings
How stable is PySide?
PySide is a work in progress and is not yet suited for application development requiring production-level stability. Work will go on to stabilize the codebase so that the first stable release can be made. Please refer to the Roadmap for PySide for an estimate of the stable releases.
What platforms does PySide support?
PySide aims to support all the platforms Qt does. However, due to practical reasons, initial development efforts are focused on Linux/X11. Developers are encouraged to assist in porting the code to their platform of choice.
As of Dec 3, 2009, bindings exist for the Linux/X11, Maemo 5, and Mac OS X platforms. Windows port is being worked on.
Which Qt versions are supported?
PySide development began on Qt 4.5. Now, Qt 4.6 is supported as well.
How about the Python versions?
Currently, only 2.5 and 2.6 are supported. Work on Python 3.x will start in early 2010.
Binding Generator
What is the binding generator?
Here the name generator refers actually to an application composed of a set of generator classes that output different source code files based on information contained inside C++ header files and XML description file(s). We call our generator boostpythongenerator after the kind of source code that it outputs. You can find more details on the generator page.
What are the dependencies of the boostpythongenerator?
Just Qt/QtCore and the API Extractor.
What is the API Extractor?
The API Extractor is a tool that parses C++ header files from a given library and merges the collected information with a description, written by the user in XML, of how it should expose to a high level target language. It actually started as a fork of QtScriptGenerator, which is a monolithic application composed of generator and extractor code, and we converted the former component to a library. QtScriptGenerator is itself a fork of the generator used to create the Qt Jambi bindings.
How API Extractor is used?
The API Extractor comes as a library that should be used by a generator front-end designed to output binding code for the desired high level target language.
What are the dependencies of API Extractor?
QtCore, QtXml and boost::graph (for topological sort of the class dependency graph).
Are there any similar tools around?
Py++ is very similar to our generator as it is now, except that other generator front-ends could be created to output binding codes of different approaches (CPython, Cython, ctypes, etc). There are QtScriptGenerator and Qt Jambi, but they are tied to their target languages.
Creating bindings
Can I wrap non-Qt libraries?
Although it is our goal that the generator could be used to create bindings for any C++ (and even C) libraries there’s still very much Qt specific stuff in the tool components. Nevertheless, we will keep changing the generator system until all produced binding code does not have any unnecessary dependency on the Qt library.
Is there any runtime dependency on the generated binding?
At the moment the runtime dependencies are Boost.Python, Qt libraries and libpysidebase. The last one is a library that takes care of the relationship between C++ objects and the associate Python wrappers, issues of ownership and Qt signals. libpysidebase is part of the PySide bindings.
But I don’t want to depend on PySide for my bindings, they’re not even based on Qt!
As we said before, it is our goal to make the binding generator generic, and this includes moving out some parts of libpysidebase leaving only Qt specific stuff, like signal/slot management. For the time being, the generator will be useful only for people creating bindings of libraries built on top of Qt.
What do I have to do to create my bindings?
Most of the work is already done by the API Extractor. The developer creates a typesystem file describing how to export the C++ library to the target language. The generator will output the headers and implementation files with the Boost.Python code that will wrap the target library for Python.
What is a Typesystem file?
It is an XML description on how the C++ library should be exported to the target language of the binding. If any class, function or method must be renamed, a method parameter removed, a C++ type declared as convertible, a class not exported, any hand written code to be added and so on, the typesystem file is the place to put those changes. Various other changes can be described on the XML file, check the typesystem format reference and binding creation tutorial for more information.
But you told me that the generator would automate the task of binding generation and set me free of boring stuff! How is that?
Yes, we told you that, but it’s kind of unavoidable to give some information to the system about the semantics of the library to be wrapped. There are subtle things like object ownership that the generator cannot discover by itself.
What about object ownership?
Sometimes a library method or function receives an object and becomes responsible for its life and death. The generator must be made aware of such behavior through the typesystem description. Let’s use an example: an object is instantiated in the target language (being this object the wrapper of a C++ object), and passed as a parameter to a C++ wrapped function which destroys the underlying C++ object leaving the wrapper in a inconsistent state.
Writing XML files is boring, do you provide a tool to create the description files?
Not yet, but we have plans for a script that checks your library and create an initial typesystem XML for it, just to help starting a new binding project. We also have an idea for a graphical tool to present the classes, functions and other stuff from the library to be wrapped and let you check what should be exported, renamed, etc. But right now it is just an idea, since for the time being we will be focusing on stabilizing and improving the PySide bindings.
What is ‘inject code’?
That’s how we call customized code that will be injected into the generated code at specific locations. They are specified inside the typesystem.
Which build system do you recommend?
Although any would do, we like the CMake build system, which is used by API Extractor, binding generator and PySide. You can refer to the build files from any of those projects as examples to create yours.
Can I write closed-source bindings with the generator?
Yes, as long as you use a LGPL version of Qt, due to runtime requirements.
How can I document my project?
The binding generator can also generate the API documentation based on the C++ headers documentation using the qdoc syntax. Optionally you can inject documentation at specific parts. Like the inject code, the customized documentation is specified inside the typesystem.
Is there any current limitation within the generator/API Extractor?
The generator currently does not automatically detect implicit C++ type conversions. Also the code snippets in function documentation and examples are still in C++ inside the generated documentation, and they should be altered using typesystem tags.
