Important

翻译是一项社区工作：ref：你可以加入<translation_guidelines>。此页面目前翻译进度为 96.34%。

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. 处理插件

Processing Plugins can be used to process data. They are easier to develop, more specific and more lightweight than Python Plugins. Writing a Processing plugin explains when the use of Processing algorithms is appropriate and how to develop them.

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文件的路径即可。

This code will run before QGIS initialization is complete. This method is very useful for cleaning sys.path, which may have undesirable paths, or for isolating/loading the initial environment without requiring a virtual environment, e.g. homebrew or MacPorts installs on Mac.

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的无缝集成。