• Intro
• Downloads
• Community
• Development
• News
• TALK

Python/Harmattan/Getting started with Harmattan Python

[edit] How to setup the device

Depending on the device model that you are using, some extra steps are needed to have Python installed on it. Currently there are two models running Meego 1.2 Harmattan:

• N950: this is the developer edition and comes with Python, PySide and bindings for QtMobility already installed.
• N9: this is the mass-market end-user device. Development packages does not come pre-installed. See below how to install Python on it!

[edit] Developer mode

Meego 1.2 Harmattan has a special mode - Developer Mode - that enables connectivity between the device and the software development kit (SDK) running on the host. This mode is useful to test applications into device as you develop. Follow the instructions here to enable/disable it.

Once you have got connected to the device using e.g. ssh, you can use devel-su command to become superuser. Use rootme as password and you become root.

$ devel-su
Password:

However, this will not allow you to execute unregistered scripts or applications. See section Security framework below to get more information about security on MeeGo 1.2 Harmattan environment.

[edit] Installing only Python

Following the steps shown in the last section you will be able to use apt-get. This application is responsible for package handling on Debian like distributions. If you want to install other modules, like bindings for Qt and QtMobility, see the topic below. As they depend on Python, it will be automatically installed too - there is no need to install just Python before them.

To have only Python installed on your device, run:

$ apt-get update
...

$ apt-get install python

Welcome to the Python world!

[edit] Installing other Python-related packages

MeeGo 1.2 Harmattan platform uses QtQuick as its preferred method to develop interfaces. The PySide project provides Python bindings for Qt allowing Python developers to develop their interfaces. Here you can find useful information on how to develop using PySide/QtQuick/QML. If you plan to develop applications that use just Qt (without QML) they will not integrate (use and feel) with the native interface.

To install these new packages you can continue from the same terminal opened in the last section. Again, use apt-get to install all the needed packages:

# Install PySide:
$ apt-get install python-pyside

There are also bindings for QtMobility. To install them:

# Install PySide-QtMobility
$ apt-get install python-qtmobility

There are some other modules already ported / being ported and the easiest way to install all of them is:

# Install all available python bindings
$ apt-get install python-modules-all

[edit] Tasting PySide/QML

If you have skipped any of the previous sections and have PySide installed you can see here an example taken from PySide documentation website.

QML is a declarative language designed to describe the user interface of a program: both what it looks like, and how it behaves. In QML, a user interface is specified as a tree of objects with properties. In this tutorial we will show how you can make a simple Hello World application with PySide and QML.

A PySide/QML application consists, at least, of two different files – a file with the QML description of the user interface, and a python file which loads the qml file. To avoid problems for now, don’t forget to save both files in the same folder.

Here is a simple QML file, called view.qml:

import Qt 4.7
 
Rectangle {
    width: 200
    height: 200
    color: "red"
 
    Text {
        text: "Hello World"
        anchors.centerIn: parent
    }
}

We start by importing Qt 4.7. As it is pretended that QtQuick has a different build schedule than Qt/PySide, in the near future you will have to change this to import QtQuick 1.0. But for now, it works as is.

The rest of the QML code, is pretty straigthforward for those who have used previously HTML or XML files. Basically, we are creating a red rectangle with the size 200*200 and, inside that rectangle, we are adding a Text element which says Hello World. The code anchors.centerIn: parent just makes the text appear centered in relation to its imediate parent.

Now, let’s see how the code looks on the PySide. Let’s call it main.py:

#!/usr/bin/python
# -*- coding: utf-8 -*-
 
import sys
from PySide.QtCore import *
from PySide.QtGui import *
from PySide.QtDeclarative import QDeclarativeView
 
# Create Qt application and the QDeclarative view
app = QApplication(sys.argv)
view = QDeclarativeView()
# Create an URL to the QML file
url = QUrl('view.qml')
# Set the QML file and show
view.setSource(url)
view.show()
# Enter Qt main loop
sys.exit(app.exec_())

To run the example remember to use:

$ python ./main.py

As this script is not packaged/registered it will fail if you call just ./main.py. The next section better explains these concepts.

If you are already familiar with PySide and have followed our tutorials, much of this code is already familiar. The only novelties is that you must import QDeclarativeView and set the source of the QDeclarativeView object to the URL of your QML file. Then, as any Qt widget, you call QDeclarativeView.show().

Take your time exploring this example. You can try to do basic things as changing the colors, the text, or set other properties to each element, setting a radius on the rectangle color. Check the elements and their properties in QML Elements.

[edit] Security framework for Python scripts

To run applications (binaries and scripts) it is necessary to follow some security guidelines. Information about the implications of the security framework for applications in general can be found here.

If your dosomething.py python script is marked as executable (as the result of chmod +x dosomething.py), it is somewhere in the PATH (for example /usr/local/bin/), it starts with the line

#!/usr/bin/env python

then you can invoke it from the command line, just as any other program. This however is not exactly what you would call "end-user friendly".

Proper packaging of your python software will allow you hand it over to your friends, who will be able to use it as any other Maemo program.

The next section shows how to package your Python application.

Note: if the script is modified after it is installed it will fail to run!

[edit] Packaging

As explained in the previous section there are some restrictions to run applications/scripts. Your application has to be installed from a Debian package.

The easiest way to create Python packages for MeeGo 1.2 Harmattan is to use pyside-assistant. After a few steps you will have a Debian package ready to be installed. You will have to inform all the resources that your application needs - avoiding problems with the Security Framework. To see all supported features and how to use pyside-assistant, including an example, follow this link.