1. 引言

本文档既是教程，也是参考指南。虽然它没有列出所有可能的用例，但它应该很好地概述了主要功能。

根据GNU自由文档许可证1.3版或自由软件基金会发布的任何更新版本的条款，允许复制、分发和/或修改本文档；没有固定章节，没有封面文本，也没有封底文本。

许可证副本包含在部分中 GNU免费文档许可证 。

本许可证还适用于本文档中的所有代码片段。

在QGIS0.9中首次引入了对Python的支持。在QGIS Desktop中使用Python有多种方法(以下各节将介绍)：

  • 在QGIS内的Python控制台中发布命令

  • 创建和使用插件

  • 在QGIS启动时自动运行Python代码

  • 创建处理算法

  • 为QGIS中的表达式创建函数

  • 基于QGIS API创建自定义应用程序

此外，还可以为QGIS Server提供Python绑定，包括Python插件(请参阅 QGIS服务器和Python )和可用于将QGIS服务器嵌入到Python应用程序中的Python绑定。

有一个 complete QGIS C++ API 引用，该引用记录了QGIS库中的类。 The Pythonic QGIS API (pyqgis) 几乎与C++API相同。

学习如何执行常见任务的另一个很好的资源是从 plugin repository 并检查他们的代码。

1.1. 在Python控制台中编写脚本

QGIS提供了一个集成的 Python console 用于脚本编写。它可以从 Plugins ► Python Console 菜单：

../../_images/console.png

图 1.4 QGIS Python控制台

上面的屏幕截图说明了如何获取当前在层列表中选择的层，显示其ID，如果是矢量层，则显示特征计数。对于与QGIS环境的交互，有一个 iface 变量，该变量是 QgisInterface 。该界面允许访问地图画布、菜单、工具栏和QGIS应用程序的其他部分。

为了方便用户，以下语句在控制台启动时执行(将来可以设置更多的初始命令)

from qgis.core import *
import qgis.utils

对于那些经常使用控制台的人，设置触发控制台的快捷方式(在 Settings ► Keyboard shortcuts... )

1.2. Python插件

QGIS的功能可以使用插件进行扩展。插件可以用Python语言编写。与C++插件相比，它的主要优势是分发简单(不需要为每个平台编译)和更容易开发。

自从引入了对Python的支持以来，已经编写了许多涵盖各种功能的插件。插件安装程序允许用户轻松获取、升级和删除Python插件。请参阅 Python Plugins 页面，了解有关插件和插件开发的更多信息。

在Python中创建插件很简单，请参见 开发Python插件 以获取详细说明。

备注

此外，QGIS服务器上也提供了Python插件。看见 QGIS服务器和Python 了解更多细节。

1.2.1. 正在处理插件

处理插件可用于处理数据。它们比Python Plugins更容易开发、更具体、更轻量级。 编写处理插件 解释何时适合使用处理算法，以及如何开发这些算法。

1.3. 在QGIS启动时运行Python代码

每次启动QGIS时，都有不同的方法来运行Python代码。

  1. 创建Startup.py脚本

  2. 设置 PYQGIS_STARTUP 环境变量添加到现有的Python文件

  3. 使用指定启动脚本 --code init_qgis.py 参数。

1.3.1. 这个 startup.py 文件

每次启动QGIS时，都会在用户的Python主目录和系统路径列表中搜索名为的文件 startup.py 。如果该文件存在，则由嵌入式Python解释器执行该文件。

用户主目录中的路径通常位于以下位置：

  • Linux： .local/share/QGIS/QGIS3

  • Windows: AppData\Roaming\QGIS\QGIS3

  • MacOS： Library/Application Support/QGIS/QGIS3

默认系统路径取决于操作系统。要查找适合您的路径，请打开Python控制台并运行 QStandardPaths.standardLocations(QStandardPaths.AppDataLocation) 要查看默认目录列表，请执行以下操作。

这个 startup.py 在应用程序启动的早期，在QGIS中初始化Python时，会立即执行脚本。

1.3.2. PYQGIS_STARTUP环境变量

在QGIS初始化完成之前，您可以通过设置 PYQGIS_STARTUP 环境变量设置为现有Python文件的路径。

此代码将在QGIS初始化完成之前运行。此方法对于清理sys.Path非常有用，它可能具有不需要的路径，或者用于隔离/加载初始环境而不需要虚拟环境，例如安装在Mac上的自制软件或MacPorts。

1.3.3. 这个 --code 参数

您可以将定制代码作为启动参数提供给QGIS执行。要执行此操作，请创建一个python文件，例如 qgis_init.py ，从命令行使用执行和启动QGIS qgis --code qgis_init.py 。

代码提供方式： --code 在加载应用程序组件之后，在QGIS初始化阶段的后期执行。

1.3.4. 适用于Python的其他参数

为您的 --code 脚本或对于执行的其他Python代码，您可以使用 --py-args 争论。之后发生的任何争执 --py-args 在此之前， -- Arg(如果存在)将被传递给Python，但被QGIS应用程序本身忽略。

在下面的示例中， myfile.tif 将通过以下方式提供 sys.argv ，但不会由QGIS加载。鉴于 otherfile.tif 将由QGIS加载，但不存在于 sys.argv 。

qgis --code qgis_init.py --py-args myfile.tif -- otherfile.tif

如果想要从Python中访问每个命令行参数，可以使用 QCoreApplication.arguments()

QgsApplication.instance().arguments()

1.4. Python应用程序

创建自动化流程的脚本通常很方便。使用PyQGIS，这是完全可能的-导入 qgis.core 模块，对其进行初始化，就可以进行处理了。

或者您可能想要创建一个使用地理信息系统功能的交互式应用程序-执行测量，将地图导出为PDF，...这个 qgis.gui 模块提供了各种图形用户界面组件，最著名的是地图画布小部件，它可以结合到应用程序中，并支持缩放、平移和/或任何进一步的自定义地图工具。

必须配置PyQGIS自定义应用程序或独立脚本以定位QGIS资源，例如投影信息以及用于读取矢量和栅格图层的提供程序。通过在应用程序或脚本的开头添加几行代码来初始化QGIS资源。为定制应用程序和独立脚本初始化QGIS的代码类似。下面提供了每种方法的示例。

备注

做 not 使用 qgis.py 作为你的剧本的名字。由于脚本的名称将隐藏绑定，因此Python将无法导入绑定。

1.4.1. 在独立脚本中使用PyQGIS

要启动独立脚本，请在脚本开头初始化QGIS资源：

 1from qgis.core import *
 2
 3# Supply path to qgis install location
 4QgsApplication.setPrefixPath("/path/to/qgis/installation", True)
 5
 6# Create a reference to the QgsApplication.  Setting the
 7# second argument to False disables the GUI.
 8qgs = QgsApplication([], False)
 9
10# Load providers
11qgs.initQgis()
12
13# Write your code here to load some layers, use processing
14# algorithms, etc.
15
16# Finally, exitQgis() is called to remove the
17# provider and layer registries from memory
18qgs.exitQgis()

首先，我们将 qgis.core 模块并配置前缀路径。前缀路径是QGIS在系统上的安装位置。它是在脚本中通过调用 setPrefixPath() 方法。的第二个论点 setPrefixPath() 设置为 True ，指定要使用的默认路径。

QGIS安装路径因平台而异；查找适用于您的系统的最简单方法是使用 在Python控制台中编写脚本 在QGIS中，查看运行以下命令的输出：

QgsApplication.prefixPath()

配置前缀路径后，我们保存对 QgsApplication 在变量中 qgs 。第二个参数设置为 False ，指定我们不打算使用该图形用户界面，因为我们正在编写独立的脚本。使用 QgsApplication 配置后，我们通过调用 initQgis() 方法。

qgs.initQgis()

初始化QGIS后，我们就可以编写脚本的其余部分了。最后，我们通过调用 exitQgis() 从内存中删除数据提供程序和层注册表。

qgs.exitQgis()

1.4.2. 在自定义应用程序中使用PyQGIS

两者之间的唯一区别是 在独立脚本中使用PyQGIS 而定制的PyQGIS应用程序是实例化 QgsApplication 。经过 True 而不是 False 以指示我们计划使用图形用户界面。

 1from qgis.core import *
 2
 3# Supply the path to the qgis install location
 4QgsApplication.setPrefixPath("/path/to/qgis/installation", True)
 5
 6# Create a reference to the QgsApplication.
 7# Setting the second argument to True enables the GUI.  We need
 8# this since this is a custom application.
 9
10qgs = QgsApplication([], True)
11
12# load providers
13qgs.initQgis()
14
15# Write your code here to load some layers, use processing
16# algorithms, etc.
17
18# Finally, exitQgis() is called to remove the
19# provider and layer registries from memory
20qgs.exitQgis()

现在，您可以使用QGISAPI--加载层并执行一些处理，或者使用地图画布启动一个图形用户界面。可能性是无穷的：-)

1.4.3. 运行自定义应用程序

如果QGIS库和适当的Python模块不在已知位置，您需要告诉您的系统在哪里搜索它们-否则，Python将报告：

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

这可以通过设置 PYTHONPATH 环境变量。在以下命令中， <qgispath> 应替换为您的实际QGIS安装路径：

  • 在Linux上： export PYTHONPATH=/<qgispath>/share/qgis/python

  • on Windows: set PYTHONPATH=c:\<qgispath>\python

  • 在MacOS上： export PYTHONPATH=/<qgispath>/Contents/Resources/python

现在，到PyQGIS模块的路径是已知的，但它们依赖于 qgis_core 和 qgis_gui 库(Python模块仅用作包装器)。操作系统可能不知道这些库的路径，然后您将再次收到导入错误(消息可能因系统而异)：

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

通过将QGIS库所在的目录添加到动态链接器的搜索路径来修复此问题：

  • 在Linux上： export LD_LIBRARY_PATH=/<qgispath>/lib

  • on Windows: set PATH=C:\<qgispath>\bin;C:\<qgispath>\apps\<qgisrelease>\bin;%PATH% where <qgisrelease> should be replaced with the type of release you are targeting (eg, qgis-ltr, qgis, qgis-dev)

可以将这些命令放入负责启动的引导脚本中。使用PyQGIS部署自定义应用程序时，通常有两种可能性：

  • 要求用户在安装您的应用程序之前安装QGIS。应用程序安装程序应该查找QGIS库的默认位置，如果找不到，则允许用户设置路径。这种方法的优点是更简单，但它需要用户执行更多的步骤。

  • 将QGIS与您的应用程序一起打包。发布应用程序可能更具挑战性，程序包也会更大，但用户将免于下载和安装额外软件的负担。

这两种部署模式可以混合使用。您可以在Windows和MacOS上提供独立的应用程序，但对于Linux，将GIS的安装留给用户和他的包管理器。

1.5. 关于PyQt和SIP的技术说明

我们决定使用Python，因为它是最受欢迎的脚本语言之一。QGIS3中的PyQGIS绑定依赖于SIP和PyQt5。之所以使用SIP而不是更广泛使用的SWIG，是因为QGIS代码依赖于Qt库。Qt(PyQt)的Python绑定是使用SIP完成的，这允许将PyQGIS与PyQt无缝集成。