This chapter focuses on the basic information necessary to start developing a QGIS plugin. Topics that will be approached will include the following:
- Where to get help to solve your PyQGIS problems
- How to set up a development environment that can resolve PyQGIS and PyQt API names during code editing
- How to interactively test your snippet using the QGIS Python console and some useful classes that can be used everywhere
- Creating a basic plugin using Plugin Builder
- Analyzing your first basic plugin to know its structure
- Setting up a runtime debugging environment that can be useful in developing complex plugins
One of the characteristics of most free software projects is that their documentation is freely available and can be used for learning. QGIS is one of the best-documented projects, thanks to training material, a coding cookbook, and the automatic documentation of its Application Programming Interfaces (APIs).
In this chapter, we will focus on main resources that are available on the web to learn how to script QGIS and how to solve your scripting problems.
The main resource is a community content-driven cookbook that gives a general introduction to scripting QGIS. You can find this documentation at http://www.qgis.org/en/docs/index.html.
You have to choose the QGIS target version of your plugin and then choose the PyQGIS Developer Cookbook link. If you are interested in the latest QGIS APIs, you have to choose the testing version or directly go to http://docs.qgis.org/testing/en/docs/pyqgis_developer_cookbook/.
If you need a copy on your system, you can also download a PDF version of the cookbook from http://docs.qgis.org/<qgis version or testing>/pdf/.
For example, if you need the documentation for version 2.2, you have to direct your browser to http://docs.qgis.org/2.2/pdf/.
However, if you need documentation for a version under development, you can visit http://docs.qgis.org/testing/pdf/.
Once you open the PDF documentation page, you can choose your preferred translation.
APIs are the doors that use the components of a software program. As a program evolves, the APIs can change affecting, in our case, all the plugins that directly use them.
The biggest QGIS API changes append jumping from version 1.8 to 2.0 and will happen jumping from 2.x to 3.x, but moving from one version to another, there are new APIs added and others are deprecated because of the normal development life cycle of complex software. Generally, deprecation and new APIs are added to enable new features (for example, multithreading visualization added in version 2.4 or the newer legend engine added in version 2.6) or due to code refactoring (refer to http://en.wikipedia.org/wiki/Code_refactoring).
So, depending on API changes and on what QGIS version you want to integrate your code into, you should use one API set or another, or better, write code that can be executed in multiple QGIS versions.
API documentation is automatically generated from the QGIS code and can be found at http://qgis.org/api/, where you can look for the class that you need.
For example, if you need to know public methods of the QgsVectorLayer class in QGIS 2.8, one of the long term release versions, you can refer to http://qgis.org/api/2.8/classQgsVectorLayer.html, or for the latest development version, http://qgis.org/api/classQgsVectorLayer.html.
It should be mentioned that QGIS is mainly written in C++ and its API documentation follows C++ notation. Most of the methods of the QGIS classes are available as a Python bind. The way to discover whether a method is exported to Python is to test it in the QGIS Python Console or read about its class documentation in the QGIS Python Console, as described in the next chapter.
One of the advantages of the open source project is that you can talk directly to other developers and frequently with the core developers of the project. QGIS has three official ways to support development and problem resolution.
All official mailing lists are listed at http://qgis.org/en/site/getinvolved/mailinglists.html.
There are two extremely important lists from the user's point of view, one for developers (QGIS core and plugin developers) and the other for users. Depending on your profile, choose one list:
- Developer list: For this, refer to http://lists.osgeo.org/mailman/listinfo/qgis-developer
- User list: For this, refer to http://lists.osgeo.org/mailman/listinfo/qgis-user
These lists can be read and searched for using an online service at http://osgeo-org.1560.x6.nabble.com/Quantum-GIS-f4099105.html, where you can also find lists of other QGIS sub-projects or the mailing lists of several other local QGIS user groups.
If you don't find your nearest local QGIS user group, first ask in the user or developer mailing lists and, depending on the answer, try to create a new QGIS local group and announce it to the community.
Internet Relay Chat (IRC) is a fantastic way to get real-time support from users and developers. Remember that this help is always voluntary and the answers depend on your politeness and the available time of the connected users.
You can connect to the #qgis channel at the http://www.freenode.net server with your preferred IRC client via http://webchat.freenode.net/?channels=#qgis. Alternatively, you can connect using the gitter service via https://gitter.im/qgis/QGIS.
The philosophy of IRC problem solving is condensed in the first chat message sent to you by the #qgis channel; it will be Don't ask to ask, just ask and hang around a while to see if someone answers. Please refer to http://osgeo.pastebin.com/ instead of pasting more than five lines.
Technical social networks such as Stack Exchange have a GIS sub-project that can be accessed from http://gis.stackexchange.com. Here you can look for problems reported by other users about QGIS and the answers that are given by other users or directly by QGIS core developers.
Messages relating to QGIS can be found by looking for the qgis tag, for example, http://gis.stackexchange.com/?tags=qgis.
In Stack Exchange, the IRC channel, and the mailing lists, you can actively support other users who have problems that you have have already solved.
An important way to support a QGIS project, other than funding it, is by reporting bugs that are packaged with a detailed use case and data that allows others to replicate the problem. This will speed up bug fixing.
There are two kinds of issues: those that are related to QGIS or its core plugins (such as Processing) and those that are related to third-party plugins that you can install with Plugin Manager.
To report a QGIS issue or a core plugin issue, you need an OSGeo account, created at https://www.osgeo.org/cgi-bin/ldap_create_user.py, using which you can log in to the QGIS redmine bug tracker to report issues at http://hub.qgis.org/projects/quantum-gis/issues.
A good guide to reporting a QGIS issue is available at:
https://www.qgis.org/en/site/getinvolved/development/bugreporting.html
Reporting a third-party plugin issue depends on the plugin developer and where he/she decides to host the bug tracker. You can find this information in the Plugin Manager, as shown in the following screenshot:
If you are looking for the link tracker, it will be found in the area marked by the red box in the second link, tracker. Other useful links can be found in the area marked in red. The first link points to the homepage plugin, where the plugin is described. The third link points to the the code repository of the plugin. In the QGIS plugin central repository, every plugin is accepted only if it has a lease tracker and a code repository.