PyQGIS developer cookbook - Documentation

PyQGIS developer cookbook

Release 3.4 QGIS Project

Mar 15, 2020

Contents

1 Introduction

1

1.1 Scripting in the Python Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.2 Python Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.3 Running Python code when QGIS starts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.4 Python Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.5 Technical notes on PyQt and SIP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2 Loading Projects

7

3 Loading Layers

9

3.1 Vector Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

3.2 Raster Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

3.3 QgsProject instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

4 Using Raster Layers

15

4.1 Layer Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

4.2 Renderer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

4.3 Query Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

5 Using Vector Layers

19

5.1 Retrieving information about attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

5.2 Iterating over Vector Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

5.3 Selecting features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

5.4 Modifying Vector Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

5.5 Using Spatial Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

5.6 Creating Vector Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

5.7 Appearance (Symbology) of Vector Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

5.8 Further Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

6 Geometry Handling

39

6.1 Geometry Construction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

6.2 Access to Geometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

6.3 Geometry Predicates and Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

7 Projections Support

43

7.1 Coordinate reference systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

7.2 CRS Transformation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

8 Using the Map Canvas

47

8.1 Embedding Map Canvas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

8.2 Rubber Bands and Vertex Markers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

8.3 Using Map Tools with Canvas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

i

8.4 Writing Custom Map Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 8.5 Writing Custom Map Canvas Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

9 Map Rendering and Printing

53

9.1 Simple Rendering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

9.2 Rendering layers with different CRS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

9.3 Output using print layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

10 Expressions, Filtering and Calculating Values

57

10.1 Parsing Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

10.2 Evaluating Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

10.3 Handling expression errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

11 Reading And Storing Settings

61

12 Communicating with the user

63

12.1 Showing messages. The QgsMessageBar class . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

12.2 Showing progress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

12.3 Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

13 Authentication infrastructure

67

13.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

13.2 Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

13.3 QgsAuthManager the entry point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

13.4 Adapt plugins to use Authentication infrastructure . . . . . . . . . . . . . . . . . . . . . . . . . 71

13.5 Authentication GUIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

14 Tasks - doing heavy work in the background

75

14.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

14.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

15 Developing Python Plugins

81

15.1 Structuring Python Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

15.2 Code Snippets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

15.3 Using Plugin Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

15.4 IDE settings for writing and debugging plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

15.5 Releasing your plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

16 Writing a Processing plugin

101

17 Network analysis library

103

17.1 General information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

17.2 Building a graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

17.3 Graph analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

18 QGIS Server Python Plugins

111

18.1 Server Filter Plugins architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

18.2 Raising exception from a plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

18.3 Writing a server plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

18.4 Access control plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

19 Cheat sheet for PyQGIS

121

19.1 User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

19.2 Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

19.3 Toolbars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

19.4 Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

19.5 Canvas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

19.6 Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

19.7 Table of contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

19.8 Advanced TOC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

ii

19.9 Processing algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 19.10 Decorators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 19.11 Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

iii

iv

1 CHAPTER

Introduction

This document is intended to be both 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.

? Scripting in the Python Console ? Python Plugins ? Running Python code when QGIS starts

? The startup.py file ? The PYQGIS_STARTUP environment variable ? Python Applications ? Using PyQGIS in standalone scripts ? Using PyQGIS in custom applications ? Running Custom Applications ? Technical notes on PyQt and SIP

Python support was first introduced in QGIS 0.9. There are several ways to use Python in QGIS Desktop (covered in the following sections):

? Issue commands in the Python console within QGIS ? Create and use plugins ? Automatically run Python code when QGIS starts ? Create custom applications based on the QGIS API Python bindings are also available for QGIS Server, including Python plugins (see QGIS Server Python Plugins) and 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. The Pythonic QGIS API (pyqgis) is nearly identical to the C++ API. A good resource for learning how to perform common tasks is to download existing plugins from the plugin repository and examine their code.

1

PyQGIS developer cookbook, Release 3.4

1.1 Scripting in the Python Console

QGIS provides an integrated Python console for scripting. It can be opened from the Plugins Python Console menu:

Fig. 1.1: 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 the QGIS environment, there is an iface variable, which is an instance of QgisInterface. This interface allows access to the map canvas, menus, toolbars and other parts of the QGIS application. For user convenience, the following statements are executed when the console is started (in the 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 Settings Keyboard shortcuts. . . )

1.2 Python Plugins

The functionality of QGIS can be extended using plugins. Plugins can be written in Python. The main advantage over C++ plugins is simplicity of distribution (no compiling for each platform) 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 Plugins page for more information about plugins and plugin development. Creating plugins in Python is simple, see Developing Python Plugins for detailed instructions.

Note: Python plugins are also available for QGIS server. See QGIS Server Python Plugins for further details.

1.3 Running Python code when QGIS starts

There are two distinct methods to run Python code every time QGIS starts. 1. Creating a startup.py script

2

Chapter 1. Introduction

 ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download