Debugging QGIS Python scripts

In this recipe, we will configure Eclipse to debug QGIS Python scripts. This setup will allow you to interactively watch the execution of programs as well as pause the execution as needed. This kind of interactive debugging is particularly useful in a GUI program such as QGIS because in addition to the user interface, there are program functions happening behind the scenes. Debugging programs that have processes in the foreground and background can be extremely difficult. This interactive debugging approach makes the development of complex applications such as these much more efficient by stepping through each part of the program as it is executed. You can see what is happening in real time and troubleshoot more easily.

How to do it...

Both QGIS and Eclipse must be configured for debugging so that the two pieces of software can communicate. Eclipse attaches itself to QGIS in order to give you insights into the Python scripts running in QGIS. This approach allows you to run scripts in a controlled way that can pause the execution while you monitor the program to catch bugs as they occur.

Configuring QGIS

The following steps will add two plugins to QGIS; this will allow Eclipse to communicate with QGIS. The first plugin, Plugin Reloader, allows you to reload a QGIS plugin into the memory without restarting QGIS for faster testing. The second plugin, Remote Debug, connects QGIS to Eclipse. Remote Debug is an experimental plugin, so we must ensure that experimental plugins are visible to the QGIS plugin manager in the list of the available plugins. This can be done in the following way:

1. Start QGIS.
2. Under the Plugins menu, select Manage and Install Plugins...
3. In the left pane of the Plugins dialog, select the Settings tab.
4. Scroll down the Settings window and ensure that the Show also experimental plugins checkbox is checked, as shown in the following screenshot:
   

5. Click on the OK button.
6. Select the tab labeled All in the pane on the left-hand side of the Plugins window.
7. In the Search dialog at the top of the window, search for Plugin Reloader.
8. Select Plugin Reloader from the search results and then click on the Install Plugin button.
9. Next, search for the Remote Debug plugin and install it as well.
10. Finally, install the HelloWorld plugin too.

Configuring Eclipse

Now that QGIS is configured for debugging in Eclipse, we will configure Eclipse to complete the debugging communication loop, as shown in the following steps:

1. Start Eclipse.
2. In the File menu, select New and then click on Project.
3. Select General and then click on Project from the New Project dialog.
4. Click on the Next> button.
5. Give the project the name HelloWorld Plugin.
6. Click on the Finish button.
7. Select the new HelloWorld plugin project in the project explorer window and select New. Then, click on Folder from the File menu.
8. In the New Folder dialog, click on the Advanced>> button.
9. Choose the Link to alternate location (Linked Folder) radio button.
10. Click on the Browse button and browse to the location of the HelloWorld plugin folder.

    Tip

    You can find the location of the HelloWorld plugin from within the QGIS plugin manager, as shown in the following screenshot:

    

11. Click on the Finish button.

Testing the debugger

In the previous parts of this recipe, we configured Eclipse and QGIS so they could work together to debug QGIS plugins. In this section, we will test the configuration using the simplest possible plugin, HelloWorld, to run Eclipse using the Debug Perspective. We will set up a breakpoint in the plugin to pause the execution and then monitor the plugins execution from within Eclipse, as follows:

1. Under the HelloWorld folder, open the HelloWorld.py file.
2. From the Eclipse Window menu, select Open Perspective and then click on Other....
3. From the Open Perspective dialog, select Debug.
4. Click on the OK button.
5. Scroll to the first line of the hello_world() function and double-click on the left-hand side of the line number to set a breakpoint, which is displayed as a green-colored icon:
   

6. From the Pydev menu, select Start Debug Server.
7. Verify that the server is running by looking for a message in the Debug console at the bottom of the window, similar to the following:

   Debug Server at port: 5678
   

8. Switch over to QGIS.
9. From the QGIS Plugins menu, select Remote Debug and then select the Remote Debug command.
10. Verify that the QGIS status bar in the lower-left corner of the window displays the following message:

    Python Debugging Active
    

11. Now select HelloWorld from the QGIS Plugins menu and then select HelloWorld.
12. Switch back to Eclipse.
13. Verify that the hello_world() function is highlighted at the breakpoint.
14. From the Run menu, select Resume.
15. Switch back to QGIS.
16. Verify that the HelloWorld dialog box has appeared.

How it works...

The Remote Debug plugin acts as a client to the PyDev debug server in order to send the Python script's execution status from QGIS to Eclipse. While it has been around for several versions of QGIS now, it is still considered experimental.

The Plugin Reloader plugin can reset plugins that maintain the state as they run. The HelloWorld plugin is so simple that reloading is not needed to test it repeatedly. However, as you debug more complex plugins, you will need to run it in order to reset it before each test. This method is far more efficient and easier to use than closing QGIS, editing the plugin code, and then restarting it.

Note

You can find out more about debugging QGIS, including using other IDEs, at http://docs.qgis.org/testing/en/docs/pyqgis_developer_cookbook/ide_debugging.html.