PyQGIS testing developer cookbook QGIS Project Sep 25, 2021 CONTENTS 1 Introduction 1 1.1 Scripting in the Python Console ................................... 1 1.2 Python Plugins ............................................ 2 1.2.1 Processing Plugins ...................................... 3 1.3 Running Python code when QGIS starts ............................... 3 1.3.1 The startup.py file ................................... 3 1.3.2 The PYQGIS_STARTUP environment variable ...................... 3 1.4 Python Applications ......................................... 3 1.4.1 Using PyQGIS in standalone scripts ............................. 4 1.4.2 Using PyQGIS in custom applications ............................ 5 1.4.3 Running Custom Applications ................................ 5 1.5 Technical notes on PyQt and SIP ................................... 6 2 Loading Projects 7 2.1 Resolving bad paths .......................................... 8 3 Loading Layers 9 3.1 Vector Layers ............................................. 9 3.2 Raster Layers ............................................. 12 3.3 QgsProject instance .......................................... 14 4 Accessing the Table Of Contents (TOC) 15 4.1 The QgsProject class ......................................... 15 4.2 QgsLayerTreeGroup class ...................................... 16 5 Using Raster Layers 19 5.1 Layer Details ............................................. 19 5.2 Renderer ............................................... 20 5.2.1 Single Band Rasters ..................................... 21 5.2.2 Multi Band Rasters ..................................... 21 5.3 Query Values ............................................. 22 5.4 Editing raster data .......................................... 22 6 Using Vector Layers 23 6.1 Retrieving information about attributes ................................ 24 6.2 Iterating over Vector Layer ...................................... 24 6.3 Selecting features ........................................... 25 6.3.1 Accessing attributes ..................................... 26 6.3.2 Iterating over selected features ............................... 26 6.3.3 Iterating over a subset of features .............................. 26 6.4 Modifying Vector Layers ....................................... 27 6.4.1 Add Features ........................................ 28 6.4.2 Delete Features ....................................... 28 6.4.3 Modify Features ....................................... 28 6.4.4 Modifying Vector Layers with an Editing Buffer ...................... 29 i 6.4.5 Adding and Removing Fields ................................ 30 6.5 Using Spatial Index .......................................... 31 6.6 The QgsVectorLayerUtils class .................................... 32 6.7 Creating Vector Layers ........................................ 32 6.7.1 From an instance of QgsVectorFileWriter ..................... 32 6.7.2 Directly from features .................................... 34 6.7.3 From an instance of QgsVectorLayer ......................... 35 6.8 Appearance (Symbology) of Vector Layers .............................. 36 6.8.1 Single Symbol Renderer ................................... 37 6.8.2 Categorized Symbol Renderer ................................ 38 6.8.3 Graduated Symbol Renderer ................................ 38 6.8.4 Working with Symbols ................................... 39 6.8.5 Creating Custom Renderers ................................. 42 6.9 Further Topics ............................................ 44 7 Geometry Handling 45 7.1 Geometry Construction ........................................ 45 7.2 Access to Geometry ......................................... 46 7.3 Geometry Predicates and Operations ................................. 47 8 Projections Support 51 8.1 Coordinate reference systems ..................................... 51 8.2 CRS Transformation ......................................... 52 9 Using the Map Canvas 55 9.1 Embedding Map Canvas ....................................... 56 9.2 Rubber Bands and Vertex Markers .................................. 56 9.3 Using Map Tools with Canvas .................................... 57 9.3.1 Select a feature using QgsMapToolIdentifyFeature ..................... 58 9.4 Writing Custom Map Tools ...................................... 59 9.5 Writing Custom Map Canvas Items .................................. 60 10 Map Rendering and Printing 63 10.1 Simple Rendering ........................................... 64 10.2 Rendering layers with different CRS ................................. 64 10.3 Output using print layout ....................................... 64 10.3.1 Exporting the layout ..................................... 66 10.3.2 Exporting a layout atlas ................................... 66 11 Expressions, Filtering and Calculating Values 67 11.1 Parsing Expressions .......................................... 68 11.2 Evaluating Expressions ........................................ 68 11.2.1 Basic Expressions ...................................... 68 11.2.2 Expressions with features .................................. 69 11.2.3 Filtering a layer with expressions .............................. 70 11.3 Handling expression errors ...................................... 70 12 Reading And Storing Settings 73 13 Communicating with the user 75 13.1 Showing messages. The QgsMessageBar class ............................ 75 13.2 Showing progress ........................................... 78 13.3 Logging ................................................ 78 13.3.1 QgsMessageLog ....................................... 79 13.3.2 The python built in logging module ............................. 79 14 Authentication infrastructure 81 14.1 Introduction .............................................. 81 14.2 Glossary ............................................... 82 ii 14.3 QgsAuthManager the entry point ................................... 82 14.3.1 Init the manager and set the master password ........................ 82 14.3.2 Populate authdb with a new Authentication Configuration entry .............. 83 14.3.3 Remove an entry from authdb ................................ 84 14.3.4 Leave authcfg expansion to QgsAuthManager ........................ 84 14.4 Adapt plugins to use Authentication infrastructure .......................... 85 14.5 Authentication GUIs ......................................... 86 14.5.1 GUI to select credentials .................................. 86 14.5.2 Authentication Editor GUI ................................. 86 14.5.3 Authorities Editor GUI ................................... 87 15 Tasks - doing heavy work in the background 89 15.1 Introduction .............................................. 89 15.2 Examples ............................................... 90 15.2.1 Extending QgsTask ..................................... 90 15.2.2 Task from function ..................................... 93 15.2.3 Task from a processing algorithm .............................. 94 16 Developing Python Plugins 97 16.1 Structuring Python Plugins ...................................... 97 16.1.1 Writing a plugin ....................................... 97 16.1.2 Plugin content ........................................ 98 16.1.3 Documentation ....................................... 103 16.1.4 Translation .......................................... 103 16.1.5 Tips and Tricks ....................................... 105 16.2 Code Snippets ............................................ 105 16.2.1 How to call a method by a key shortcut ........................... 106 16.2.2 Interface for plugin in the options dialog .......................... 106 16.3 IDE settings for writing and debugging plugins ............................ 107 16.3.1 Useful plugins for writing Python plugins .......................... 107 16.3.2 A note on configuring your IDE on Linux and Windows .................. 108 16.3.3 Debugging using Pyscripter IDE (Windows) ........................ 108 16.3.4 Debugging using Eclipse and PyDev ............................ 108 16.3.5 Debugging with PyCharm on Ubuntu with a compiled QGIS ................ 113 16.3.6 Debugging using PDB .................................... 114 16.4 Releasing your plugin ......................................... 115 16.4.1 Metadata and names ..................................... 115 16.4.2 Code and help ........................................ 115 16.4.3 Official Python plugin repository .............................. 116 17 Writing a Processing plugin 119 17.1 Creating from scratch ......................................... 119 17.2 Updating a plugin ........................................... 119 18 Using Plugin Layers 121 18.1 Subclassing QgsPluginLayer ..................................... 121 19 Network analysis library 123 19.1 General information ......................................... 123 19.2 Building a graph ........................................... 123 19.3 Graph analysis ............................................ 125 19.3.1 Finding shortest paths .................................... 127 19.3.2 Areas of availability ..................................... 129 20 QGIS Server and Python 131 20.1 Introduction .............................................. 131 20.2 Server API basics ........................................... 131 20.3 Standalone or embedding ....................................... 132 20.4 Server plugins ............................................. 133 iii 20.4.1 Server filter plugins ..................................... 133 20.4.2