Python 3 Porting Guide

Guide to porting Sugar Activities to Python 3.

Many activities were written in Python 2 with the PyGObject introspection library, GTK, GDK, GStreamer, and other dependencies. Activities usually did not have test cases or test coverage.

Required Skills

application development in Python,
Sugar activity development,
knowledge of differences between Python 2 and Python 3.

How to Port an Activity to Python 3:

Quiesce the activity source by making sure the activity works properly before porting, closing any solved issues, merging any pull requests or branches and releasing the last Python 2 version; see the activity maintainer checklist.
Check that a Python 3 port has not already been done; look for a python3 branch in the main repository, or any developer fork.
For activities known to work with Fedora 18, create a fedora18 branch and push; this branch will be for any future maintenance with Python 2,
Use Sugar Toolkit for GTK 3 version 0.115 or later, built for Python 3, and test that /usr/bin/python3 can import it, for example;
```
python3 -c 'import sugar3'
```
Prepare a test plan to cover each feature and user interface widget, and consider assessing coverage,
If the activity uses telepathy-python, test and fix collaboration, then port to PyGObject binding TelepathyGLib, and test again, for example;
```
import telepathy
```
should change to:
```
from gi.repository import TelepathyGLib
```
Use constants from TelepathyGLib, and minimise changes, for example;
```
from telepathy.interfaces import CHANNEL
```
should change to:
```
CHANNEL = TelepathyGLib.IFACE_CHANNEL
```
Replace calls to Channel and Connection classes of
telepathy-python with a dictionary of dbus.Interface(). Look
through the source code for constants used by Channel and Connection
objects as keys. Use these constants as keys to a dictionary of the
dbus.Interface() objects. For example;
```
Channel(self._connection.requested_bus_name, channel_path,
  ready_handler=self.__text_channel_ready_cb)
```
should change to (ensure adding all key-interface pairs):
```
self.text_channel = {}
self.text_proxy = dbus.Bus().get_object(
          self._connection.requested_bus_name, channel_path)
self.text_channel[PROPERTIES_IFACE] = dbus.Interface(
          self.text_proxy, PROPERTIES_IFACE)
```
Replace all bare references to telepathy_text_chan and
telepathy_tubes_chan
```
self.telepathy_text_chan.AddMembers(
```
should change to:
```
self.telepathy_text_chan[CHANNEL].AddMembers(
```
Test and fix collaboration before proceeding further.
If the activity uses dbus.gobject_service.ExportedGObject (deprecated and only available for Python 2), then port to CollabWrapper, and test again,
If the activity uses dbus directly, refer to dbus-python Porting to Python 3, and test again,
Port from Python 2 to Python 3.
Start your porting with 2to3 tool,

In the terminal, type:
```
2to3 -w -n *.py
```
and then review every change made,
Iterate through How to Port Python 2 code to Python 3 | Python Docs (most Sugar activities being ported to Python 3 do not need to support Python 2 as well), and Supporting Python 3: An in-depth guide changing code,
Check for integer divisions that have become floating point,
Check for use of binary data, especially in files, pipes, and subprocesses,
Check for use of Gtk.CssProvider, and if so ensure the load_from_data function is given bytes rather than unicode strings, e.g. `b"...",
Check for use of Rsvp.new_from_data for making images from SVG data, and if so ensure the function is given bytes rather than unicode strings,
Change exec value in activity.info from sugar-activity to sugar-activity3
Make Sugar Home View reload the bundle; by restarting Sugar or moving the bundle directory out of ~/Activities and back again a few seconds later,
Test the activity from Sugar, that it starts without error, that no warnings or errors are in logs, and that each user function works as before,
Check if the activity can be built,

In the terminal, type:
```
python3 setup.py dist_xo
```
Release a new version,
Update README.md to point to the released bundle,

Follow the Code Guidelines during all porting.

Write any comments in the code, by adding # README:, # TODO: and # FIXME: explaining what are the problems that you are having with that chunk of code. Put a link if it's necessary.

Releasing Activities (for maintainers)

Once an activity is ported, a new release can be made. The major version
should be greater than the existing one.

Please follow
this
guide for releasing a new version.

Avoid releasing Python 3 activities to https://activities.sugarlabs.org/ as these will not work on existing systems.

Resources:

Porting Examples:

Here are some examples of porting activities to Python 3:

Common Questions

Why does my traceback show Python 2?

Check that you have changed exec in activity.info, and that Sugar has been restarted.

Why does "consider porting to Python 3" still appear?

Check that you have changed exec in activity.info.