View source for Python/Harmattan/Getting started with Harmattan Python

== 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, [http://www.pyside.org PySide] and [http://www.pyside.org/docs/pyside-mobility/ 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!

==== Developer mode ====

Meego 1.2 Harmattan has a special mode - [http://library.developer.nokia.com/topic/MeeGo_1.2_Harmattan_API/html/guide/html/Developer_Library_Developing_for_Harmattan_Activating_developer_mode_1fa5.html 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 [http://library.developer.nokia.com/topic/MeeGo_1.2_Harmattan_API/html/guide/html/Developer_Library_Developing_for_Harmattan_Activating_developer_mode_1fa5.html 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.

 <nowiki>
$ devel-su
Password:
</nowiki>

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.

==== 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:

 <nowiki>
$ apt-get update
...

$ apt-get install python
</nowiki>

Welcome to the Python world!

==== Installing other Python-related packages ====

MeeGo 1.2 Harmattan platform uses [https://web.archive.org/web/20120929010040/http://library.developer.nokia.com/topic/MeeGo_1.2_Harmattan_API/html/guide/html/Developer_Library_Application_development_framework_ebcf.html QtQuick] as its preferred method to develop interfaces. The [http://www.pyside.org PySide] project provides Python bindings for Qt allowing Python developers to develop their interfaces. [https://web.archive.org/web/20120929010040/http://developer.qt.nokia.com/wiki/PySideDocumentation/ 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:

 <nowiki>
# Install PySide:
$ apt-get install python-pyside
</nowiki>

There are also [https://web.archive.org/web/20120929010040/http://qt-project.org/wiki/PySideDocumentation/#704d2ca247b8787c6738c5a47d3f98ec bindings] for [https://web.archive.org/web/20120929010040/http://doc.qt.nokia.com/qtmobility-1.2/index.html QtMobility]. To install them:

 <nowiki>
# Install PySide-QtMobility
$ apt-get install python-qtmobility
</nowiki>

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

 <nowiki>
# Install all available python bindings
$ apt-get install python-modules-all
</nowiki>

== Tasting PySide/QML ==

If you have skipped any of the previous sections and have PySide installed you can see here an [https://web.archive.org/web/20120929010040/http://developer.qt.nokia.com/wiki/Hello_World_in_PySide_and_QtQuick example] taken from PySide documentation website. 

[https://web.archive.org/web/20120929010040/http://doc.qt.nokia.com/4.7/qdeclarativeintroduction.html 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'':

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

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:

 <nowiki>
#!/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_())
</nowiki>

To run the example remember to use:

 <nowiki>
$ python ./main.py
</nowiki>

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 [https://web.archive.org/web/20120929010040/http://doc.qt.nokia.com/4.7/qdeclarativeelements.html QML Elements].

== 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 [https://projects.maemo.org/mediawiki/index.php/Developer_Library/Developing_for_Harmattan/Harmattan_security 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

<nowiki>
#!/usr/bin/env python
</nowiki>

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!

== 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 [[Documentation_for_pyside-assistant|link]].