Python in QGIS¶

The core application and libraries of QGIS are programmed in C++. Nevertheless, Python plays an important role in its ecosystem: Most of the pre-installed plugins and even some of the data provider modules are written in Python, and virtually all functions of the interface and the libraries are exported to a Python API (Application Programming Interface). It takes only moderate effort to author extensions to QGIS which integrate seamlessly into its user interface, create stand-alone applications using components of QGIS, such as a map window or a data backend, or run custom scripts within QGIS. To really dive into using Python in QGIS, see the PyQGIS Developer Cookbook which walks you from easy Hello World examples to writing your own applications.

Today, we will concentrate on basic functionalities of Python in QGIS, or PyQGIS for short. You will learn to run code from the integrated Python console, then write a simple Python script and finally apply the script’s functionality to your very own plugin.

Sample data for this tutorial¶

To get us started, we’ll need some data. Open QGIS and connect to the City of Helsinki’s WFS service from Layer > Add layer > Add WFS layer:

Create a new connection to URL http://kartta.hel.fi/ws/geoserver/avoindata/wfs and load the layer list. Select, for example, the Metro railway lines (Seutukartta_liikenne_metro_rata). Make sure the coordinate system is set to a projected one, like ETRS89/GK25FIN (EPSG:3879) before adding the layer.

Running PyQGIS code in console¶

Now that we’re set, let’s open QGIS’s Python console and get to work! Open it from Plugins > Python console or use the shortcut Ctrl+Alt+P on your keyboard.

Console¶

By default an iface object is imported, which allows the access to the currently active QGIS instance’s user interface. For example, we can easily retrieve the active (selected) layer, then access its type, name, and count its features:

# Get active layer:
>>> layer = iface.activeLayer()

# Let's see what we got
>>> print(type(layer))
<class 'qgis._core.QgsVectorLayer'>

>>> print(layer.sourceName())
Seutukartta_liikenne_metro_rata

>>> print(layer.featureCount())
3

The layer we got is an object of class QgsVectorLayer, which in turn is within QGIS’s core module. There are seven modules in total each housing classes critical for the program.

Above, we call QgsVectorLayer’s methods like featureCount(). You may read more on the methods in the documentation or call help() on the object for the same information:

>>> help(layer)
Help on QgsVectorLayer in module qgis._core object:

class QgsVectorLayer(QgsMapLayer, QgsExpressionContextGenerator, QgsExpressionContextScopeGenerator, QgsFeatureSink, QgsFeatureSource)
 |  QgsVectorLayer(path: str = '', baseName: str = '', providerLib: str = '', options: QgsVectorLayer.LayerOptions = QgsVectorLayer.LayerOptions())
 |  Constructor - creates a vector layer
 |
    ...

Like the documentation shows, we can use a method to access the features (=rows on the attribute table) of the layer. Let’s loop through the features and print out attributes from each feature:

>>> for feat in layer.getFeatures():
        # attributes() returns a list of attributes assosiated with that feature
        # we'll print the second entries on the lists, which correspond to the 'metrorata' column
...     print(feat.attributes()[1])
Vuosaari
Länsimetro
Mellunmäki

If the features are geographical, they’ll have geometry as well as attributes. The geometry objects have a method for calculating the length of an feature in map units. We’ll use this to our advantage and create a simple program for summing up the total length of line features in the selected layer and print this out in kilometers:

# variable to house the sum of the lengths
>>> total_length = 0

>>> for feat in layer.getFeatures():
...    geometry = feat.geometry()
...    total_length += geometry.length()

# printing and transforming the result (rounded to one decimal point) to km
>>> print("Total length of features in layer "+ layer.sourceName()+ " is:", round(total_length/1000, 1), "km")
Total length of features in layer Seutukartta_liikenne_metro_rata is: 34.8 km

Creating PyQGIS scripts¶

Great! But what if we want to show someone our cool function or reuse the code? Thankfully QGIS also includes a simple code editor, from which we can run, edit and save Python scripts. Click the middle icon on the top row of the console and an editor with blank text field should appear.

Console and editor¶

Next, apply the code created previously and make a function. The function gets the active layer, calculates the length of its features and then prints the result in the console. Although it’s in poor form to have so many separate tasks for one function, we do it like this to make things more straightforward later on.

def lineLengthCalc():
    """Sums together the length of features in a line type vector layer, then prints the result in km."""
    # get the current active layer
    layer = iface.activeLayer()

    total_length = 0

    for feat in layer.getFeatures():
        geometry = feat.geometry()
        total_length += geometry.length()

    # print out the result
    print("Total length of features in layer "+ layer.sourceName()+ " is:", round(total_length/1000, 1), "km")

# call the function
lineLengthCalc()

Run the script to make sure it works. After that, save the result as a script file lineLengthCalculator.py. You may open it anytime from the code editor.

Next up, we’ll apply the script code to an extremely simple plugin.

Python in QGIS¶

Sample data for this tutorial¶

Running PyQGIS code in console¶

Creating PyQGIS scripts¶

Creating QGIS plugins¶

Creating the plugin base¶

Initializing¶

Developing the plugin¶

Adding UI elements¶

Linking UI to code¶

Additional resources¶

Python in QGIS¶

Getting started with plugin development¶