Setting up your QGIS IDE

The Eclipse IDE and the PyDev plugin are cross-platform and free, and they possess advanced debugging tools.

Note

You can refer to http://pydev.org/manual_101_install.html in order to install PyDev correctly.

This tool makes an excellent PyQGIS IDE. Eclipse allows you to have multiple Python interpreters configured for different Python environments. When you install PyDev, it automatically finds the Python installations. On Windows, you also need to add the Python interpreter, installed with PyQGIS. On all platforms, you must tell PyDev where the PyQGIS libraries are.

Getting ready

This recipe uses Eclipse and PyDev. You can use the latest version of both the packages supported by your operating system. All platforms, except for Windows, rely on the Python interpreter. This means that there is an extra step in Windows to add the Python interpreter.

How to do it...

The following steps will walk you through the process of adding the QGIS-specific Python interpreter to Eclipse in order to support the running standalone QGIS applications or the debugging of QGIS plugins.

Adding the Python interpreter to Windows

The process used to add a Python interpreter to Eclipse on Windows is different from the process used on Linux. The following steps describe how to set up the interpreter on the Windows version of Eclipse:

1. Open Eclipse.
2. From the Window menu, select Preferences.
3. In the pane on the left-hand side of the Preferences window, click on the arrow icon next to PyDev.
4. From the list of PyDev preferences, select Interpreters.
5. In the pane labeled Python Interpreters, click on the New button.
6. In the Select interpreter dialog, name the interpreter PyQGIS.
7. Navigate to the location of the Python interpreter called python.exe, placed within the bin folder of the QGIS program folder. On OS X and Linux, you use the system's Python installation. On Windows, Python is included with QGIS. The default location on Windows is C:\Program Files\QGIS2.18\bin\python.exe, as shown in the following screenshot:
   

8. When you click on the OK button, Eclipse will attempt to automatically add every Python library it finds to the Python path to configure this interpreter. We need to control which libraries are added to prevent conflicts. Click on the Deselect All button and then click on OK:
   

9. Eclipse will issue a warning dialog because you haven't selected any core libraries. Click on the Proceed anyways button, as shown here:
   

Adding the PyQGIS module paths to the interpreter

Apart from adding the Python interpreter, you also need to add the module paths needed by PyQGIS, using the following steps. These steps will require you to switch back and forth between QGIS and Eclipse.

1. Start QGIS.
2. Select Python Console from the Plugins menu.
3. Use the sys module to locate the PyQGIS Python path, as described in the previous recipe, Setting the environment variables:

           import sys 
           sys.path 
   

4. We also want to add the PyQGIS API so the script has access to all of the QGIS functions within Eclipse. Next, find that path using the QGIS Python Console by typing the following command:

         qgis
   

5. For each path in the returned list, click on the New Folder button in Eclipse's Libraries pane for your QGIS interpreter and browse to that folder until all the paths have been added. If a given folder does not exist on your system, simply ignore it, as shown here:
   

6. Click on the OK button in the Preferences dialog.

Adding the PyQGIS API to the IDE

To take full advantage of Eclipse's features, including code completion, we will add the QGIS and Qt4 modules to the PyQGIS Eclipse interpreter preferences. The following steps will allow Eclipse to suggest the possible methods and properties of QGIS objects as you type; this feature is known as autocomplete:

1. In the PyDev preferences for the PyQGIS interpreter, select the Forced Builtins tab, as shown in the following screenshot:
   

2. Click on the New button.
3. In the Builtin to add dialog, type qgis:
   

4. Click on the OK button.

Adding environment variables

You will also need to create a PATH variable that points to the QGIS binary libraries, DLLs on Windows, and other libraries needed by QGIS at runtime. And you'll need to create this on all platforms in the following way:

1. In the PyDev preferences dialog, ensure that the PyQGIS interpreter is selected from the list of interpreters.
2. Select the Environment tab.
3. Click on the New button.
4. In the Name field, enter PATH.
5. For the Value field, add the path to the QGIS program directory and to any QGIS directories that contain binaries separated by a semicolon. The following is an example from a Windows machine:

     C:\Program Files\QGIS 2.18;C:\Program Files\QGIS 2.18\bin;
         C:\Program Files\QGIS 2.18\apps\qgis\bin;C:\Program Files\QGIS
         2.18\apps\Python27\DLLs
   

How it works...

Eclipse and PyDev use only the information you provide to run a script in the Eclipse workspace. This approach is very similar to the popular Python tool virtualenv, which provides a clean environment when writing and debugging code to ensure that you don't waste time troubleshooting issues caused by the environment.