Outdated version of the documentation. Find the latest one here.

Introductie

This document is intended to work both as a tutorial and a reference guide. While it does not list all possible use cases, it should give a good overview of the principal functionality.

Starting from 0.9 release, QGIS has optional scripting support using Python language. We’ve decided for Python as it’s one of the most favourite languages for scripting. PyQGIS bindings depend on SIP and PyQt4. The reason for using SIP instead of more widely used SWIG is that the whole QGIS code depends on Qt libraries. Python bindings for Qt (PyQt) are done also using SIP and this allows seamless integration of PyQGIS with PyQt.

There are several ways how to use Python bindings in QGIS desktop, they are covered in detail in the following sections:

  • automatically run Python code when QGIS starts
  • issue commands in Python console within QGIS
  • create and use plugins in Python
  • create custom applications based on QGIS API

Python bindings are also available for QGIS Server:

  • starting from 2.8 release, Python plugins are also available on QGIS Server (see Server Python Plugins)
  • starting from 2.11 version (Master at 2015-08-11), QGIS Server library has Python bindings that can be used to embed QGIS Server into a Python application.

There is a complete QGIS API reference that documents the classes from the QGIS libraries. Pythonic QGIS API is nearly identical to the API in C++.

A good resource when dealing with plugins is to download some plugins from plugin repository and examine their code. Also, the python/plugins/ folder in your QGIS installation contains some plugin that you can use to learn how to develop such plugin and how to perform some of the most common tasks.

Run Python code when QGIS starts

Er zijn twee afzonderlijke methoden om Python-code uit te voeren elke keer als QGIS start.

Omgevingsvariabele PYQGIS_STARTUP

You can run Python code just before QGIS initialization completes by setting the PYQGIS_STARTUP environment variable to the path of an existing Python file.

This method is something you will probably rarely need, but worth mentioning here because it is one of the several ways to run Python code within QGIS and because this code will run before QGIS initialization is complete. This method is very useful for cleaning sys.path, which may have undesireable paths, or for isolating/loading the initial environ without requiring a virt env, e.g. homebrew or MacPorts installs on Mac.

Het bestand startup.py

Every time QGIS starts, the user’s Python home directory (usually: .qgis2/python) is searched for a file named startup.py, if that file exists, it is executed by the embedded Python interpreter.

Python Console

For scripting, it is possible to take advantage of integrated Python console. It can be opened from menu: Plugins ‣ Python Console. The console opens as a non-modal utility window:

../../_images/console.png

QGIS Python-console

The screenshot above illustrates how to get the layer currently selected in the layer list, show its ID and optionally, if it is a vector layer, show the feature count. For interaction with QGIS environment, there is a iface variable, which is an instance of QgsInterface. This interface allows access to the map canvas, menus, toolbars and other parts of the QGIS application.

For convenience of the user, the following statements are executed when the console is started (in future it will be possible to set further initial commands)

from qgis.core import *
import qgis.utils

For those which use the console often, it may be useful to set a shortcut for triggering the console (within menu Settings ‣ Configure shortcuts...)

Plug-ins in Python

QGIS allows enhancement of its functionality using plugins. This was originally possible only with C++ language. With the addition of Python support to QGIS, it is also possible to use plugins written in Python. The main advantage over C++ plugins is its simplicity of distribution (no compiling for each platform needed) and easier development.

Many plugins covering various functionality have been written since the introduction of Python support. The plugin installer allows users to easily fetch, upgrade and remove Python plugins. See the Python Plugin Repositories page for various sources of plugins.

Plug-ins maken in Python is simpel, zie Python plug-ins ontwikkelen voor gedetailleerde instructies.

Notitie

Python plugins are also available in QGIS server (QGIS als OGC Data Server), see Python plug-ins voor QGIS server for further details.

Toepassingen in Python

Often when processing some GIS data, it is handy to create some scripts for automating the process instead of doing the same task again and again. With PyQGIS, this is perfectly possible — import the qgis.core module, initialize it and you are ready for the processing.

Or you may want to create an interactive application that uses some GIS functionality — measure some data, export a map in PDF or any other functionality. The qgis.gui module additionally brings various GUI components, most notably the map canvas widget that can be very easily incorporated into the application with support for zooming, panning and/or any further custom map tools.

PyQGIS custom applications or standalone scripts must be configured to locate the QGIS resources such as projection information, providers for reading vector and raster layers, etc. QGIS Resources are initialized by adding a few lines to the beginning of your application or script. The code to initialize QGIS for custom applications and standalone scripts is similar, but examples of each are provided below.

Note: do not use qgis.py as a name for your test script — Python will not be able to import the bindings as the script’s name will shadow them.

PyQGIS gebruiken in zelfstandige scripts

Initialiseer, om een zelfstandig script te starten, de bronnen voor QGIS aan het begin van het script, soortgelijk aan de volgende code:

from qgis.core import *

# supply path to qgis install location
QgsApplication.setPrefixPath("/path/to/qgis/installation", True)

# create a reference to the QgsApplication, setting the
# second argument to False disables the GUI
qgs = QgsApplication([], False)

# load providers
qgs.initQgis()

# Write your code here to load some layers, use processing algorithms, etc.

# When your script is complete, call exitQgis() to remove the provider and
# layer registries from memory
qgs.exitQgis()

We beginnen door de module qgis.core te importeren en dan het pad voor het voorvoegsel te configureren. Het pad voor het voorvoegsel is de locatie waar QGIS is geïnstalleerd op uw systeem. Het wordt in het script geconfigureerd door de methode setPrefixPath aan te roepen. Het tweede argument van setPrefixPath is om de True in te stellen, die beheert of de standaard paden worden gebruikt.

Het pad voor de installatie van QGIS varieert per platform; de eenvoudigste manier om het voor uw systeem te vinden is door de Python Console te gebruiken vanuit QGIS en te kijken naar de uitvoer bij het uitvoeren van QgsApplication.prefixPath().

Nadat het pad voor het voorvoegsel is geconfigureerd slaan we een verwijzing naar QgsApplication op in de variabele qgs. Het tweede argument wordt ingesteld op False, wat aangeeft dat we niet van plan zijn om de GUI te gebruiken omdat we een zelfstandig script schrijven. Met QgsApplication geconfigureerd laden we de gegevensproviders en registratie van lagen voor QGIS door de methode qgs.initQgis() aan te roepen. Met QGIS geïnitialiseerd zijn we klaar om de rest van het script te schrijven. Tenslotte sluiten we af door qgs.exitQgis() aan te roepen om de gegevensproviders en registratie van lagen uit het geheugen te verwijderen.

PyQGIS gebruiken in aangepaste toepassing

Het enige verschil tussen PyQGIS gebruiken in zelfstandige scripts en een aangepaste toepassing van PyQGIS is het tweede argument bij het instantiëren van QgsApplication. Geef op True in plaats van False om aan te geven dat we van plan zijn om een GUI te gaan gebruiken.

from qgis.core import *

# supply path to qgis install location
QgsApplication.setPrefixPath("/path/to/qgis/installation", True)

# create a reference to the QgsApplication
# setting the second argument to True enables the GUI, which we need to do
# since this is a custom application
qgs = QgsApplication([], True)

# load providers
qgs.initQgis()

# Write your code here to load some layers, use processing algorithms, etc.

# When your script is complete, call exitQgis() to remove the provider and
# layer registries from memory
qgs.exitQgis()

Now you can work with QGIS API — load layers and do some processing or fire up a GUI with a map canvas. The possibilities are endless :-)

Aangepaste toepassingen uitvoeren

U zult uw systeem moeten vertellen waar te zoeken naar de bibliotheken van QGIS en de toepasselijke modules voor Python als zij nog niet op ene bekende locatie staan — anders zal Python gana klagen:

>>> import qgis.core
ImportError: No module named qgis.core

This can be fixed by setting the PYTHONPATH environment variable. In the following commands, qgispath should be replaced with your actual QGIS installation path:

  • on Linux: export PYTHONPATH=/qgispath/share/qgis/python
  • on Windows: set PYTHONPATH=c:\qgispath\python

The path to the PyQGIS modules is now known, however they depend on qgis_core and qgis_gui libraries (the Python modules serve only as wrappers). Path to these libraries is typically unknown for the operating system, so you get an import error again (the message might vary depending on the system):

>>> import qgis.core
ImportError: libqgis_core.so.1.5.0: cannot open shared object file: No such file or directory

Los dit op door de mappen waar de bibliotheken van QGIS zijn opgeslagen toe te voegen aan het zoekpad van de dynamische linker:

  • on Linux: export LD_LIBRARY_PATH=/qgispath/lib
  • on Windows: set PATH=C:\qgispath;%PATH%

Deze opdrachten kunnen worden geplaatst in een bootstrap-script dat het opstarten voor zijn rekening zal nemen. Bij het uitrollen van toepaste toepassingen met behulp van PyQGIS, zijn er gewoonlijk twee mogelijkheden:

  • require user to install QGIS on his platform prior to installing your application. The application installer should look for default locations of QGIS libraries and allow user to set the path if not found. This approach has the advantage of being simpler, however it requires user to do more steps.
  • verpak QGIS tezamen met uw toepassing. Uitgeven van de toepassing ka uitdagender zijn en het pakket zal groter zijn, maar de gebruiker zal verlost zijn van de last van het downloaden en installeren van aanvullende stukken software.

De twee modellen van uitrollen kunnen worden gemixt - rol een zelfstandige toepassing uit op Windows en MacOS, laat voor Linux de installatie van QGIS over aan de gebruiker en diens pakketbeheer.