Important

翻译是一项社区工作 你可以加入。此页面目前翻译进度为 98.78%。

1. 简介

本文档既可作为教程，也可作为参考指南。虽然没有列举所有可能的案例，但是对主要功能有一个很好的概述。

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

A copy of the license is included in the section GNU Free Documentation License.

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

对于Python的支持最初是在QGIS 0.9中引入的。 目前在QGIS Desktop中使用Python的几种方法（将在以下章节中介绍）：

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

  • 创建并使用插件

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

  • 创建处理算法

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

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

Python绑定也可用于QGIS Server，包括Python插件（请参阅 QGIS Server and Python ）和Python绑定，可用于将QGIS Server嵌入到Python应用程序中。

这里有一个 完整的QGIS C++ API 参考——用于记录QGIS库中的类。 Pythonic QGIS API (pyqgis) 几乎与C ++ API相同。

学习执行常见任务的另一个好资源是从 `插件仓库<https://plugins.qgis.org/>`_下载现有插件并学习它们的代码。

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

QGIS为脚本编写提供了一个集成的 Python console 。可以从 插件->python控制台 菜单中打开 Plugins ► Python Console 。

../../_images/console.png

Fig. 1.11 QGIS Python console

上面的截图说明了如何获取图层列表中当前选定的图层，并显示其ID，如果是矢量图层，还可以显示要素个数。对于与QGIS交互环境，有一个 iface 变量，它是 QgisInterface 的一个实例。此接口允许访问地图画布、菜单、工具栏和QGIS应用程序的其他部分。

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

from qgis.core import *
import qgis.utils

对于经常使用控制台的用户，设置打开控制台的快捷键可能很有用（在设置->键盘快捷键中...） Settings ► Keyboard shortcuts...

1.2. Python Plugins (py插件)

QGIS的功能可以使用插件进行扩展。插件可以用Python编写。与c++插件相比，它的主要优点是分发简单（无需为每个平台编译）和更容易开发。

自从引入对Python的支持以来，已经编写了许多涵盖各种功能的插件。插件安装程序允许用户很容易获取、升级和移除Python插件。有关插件和插件开发的更多信息，请参阅`Python Plugins <https://plugins.qgis.org/>`_ 页面。

使用Python创建插件很简单，详细说明请参阅 Developing Python Plugins

Note

Python插件也可用于QGIS Server，更多信息，请参阅 See QGIS Server and Python

1.2.1. 处理插件

处理插件可被用于处理数据。它们比Python插件更容易开发、更具体、更轻量。 Writing a Processing plugin 阐述了什么时候该使用处理算法，并且怎么开发它们。

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初始化完成之前运行Python代码，将 PYQGIS_STARTUP 环境变量设置为现有Python文件的路径即可。

此代码将在QGIS初始化完成之前运行。此方法对于清理sys.path非常有用——可能存在不需要的路径，或用于隔离/加载初始环境——无需虚拟环境，例如在Mac上使用homebrew或MacPorts。

1.3.3. --code 参数

你可以提供自定义代码作为 QGIS 的启动参数执行。为此，请创建一个 python 文件，例如 qgis_init.py ，使用 ``qgis --code qgis_init.py``从命令行执行和启动 QGIS。

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

1.3.4. Python 的其他参数

要为 --code 脚本或执行的其他 python 代码提供其他参数，您可以使用 --py-args 参数。在 --py-args 之后和 ``--``（如果存在）之前的任何参数都将传递给 Python，但被 QGIS 应用程序本身忽略。

在下面的例子中，myfile.tif 将通过 Python 中的 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 模块，初始化它，就可以进行处理了。

或者你可能想要创建一个使用GIS功能的交互式应用程序——执行测量、将地图导出为PDF或任何其他功能... qgis.gui 模块提供了各种GUI部件，最值得注意的是可以合并到应用程序中的地图画布控件——支持缩放，平移和任何其他自定义地图工具。

必须配置PyQGIS自定义应用程序或独立脚本以定位QGIS资源，例如投影信息，用于读取矢量和栅格图层的数据提供者等。QGIS资源通过在应用程序或脚本的开头添加几行代码来初始化。自定义应用程序和独立脚本初始化QGIS的代码类似。以下提供各自的实例。

Note

*不要*使用 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() ，它控制是否使用默认路径。

QGIS安装路径因平台而异，在你的系统中找到它最简单的方法是在QGIS中使用 在Python控制台中编写脚本 并查看运行时的输出。

QgsApplication.prefixPath()

配置前缀路径后，我们在变量 qgs 中保存了一个对 QgsApplication 的引用。第二个参数设置为 False ，表示我们不打算使用GUI，因为我们正在编写一个独立的脚本。配置 QgsApplication 后 ，我们通过调用 initQgis() 方法加载QGIS数据提供者和图层注册。

qgs.initQgis()

在QGIS初始化后，我们准备编写脚本的其余部分。最后，我们通过调用 exitQgis() 从内存中移除数据提供者和图层注册。

qgs.exitQgis()

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

在独立脚本中使用PyQGIS 和自定义PyQGIS应用程序之间的唯一的区别是在实例化 QgsApplication. 传递 True 而不是 False 来表明我们计划使用GUI。

 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()

现在，你可以使用QGIS API——加载图层并执行一些处理或使用地图画布启动GUI。可能性是无止境的:-)

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

  • 在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

  • 在 Windows上: set PATH=C:\<qgispath>\bin;C:\<qgispath>\apps\<qgisrelease>\bin;%PATH% ，其中``<qgisrelease>`` 应替换成你的发布类型 (例如 qgis-ltr, qgis, qgis-dev)

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

  • 要求用户在安装应用程序之前在其平台上安装QGIS。应用程序安装程序应查找QGIS库的默认位置，并允许用户设置路径（如果未找到）。该方法更简单，但是它需要用户执行更多步骤。

  • 将QGIS与你的应用程序一起打包。发布应用程序可能更具挑战性，并且程序包将更大，但用户将免于下载和安装其他软件的负担。

这两种部署方式可以混合使用——在Windows和macOS上部署独立应用程序，但是对于Linux，将QGIS的安装留给用户和他的包管理器。

1.5. PyQt和SIP的技术说明

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