目录
1 引言
本文档既可作为教程，也可作为参考指南。 虽然它没有列出所有可能的用例，但是对主要功能有一个很好的概述。
对于 Python支持最初是在QGIS 0.9中引入的。 目前，在QGIS桌面版中有几种方法可以使用Python ，如下 ：
-
在QGIS的Python控制台中
-
创建并使用插件
-
QGIS启动时自动运行Python代码
-
基于QGIS API创建自定义应用程序
Python绑定也可用于QGIS服务，包括Python插件（请参阅QGIS Server Python插件）和Python绑定，可用于将QGIS服务嵌入到Python应用程序中。 这里有一个完整的QGIS API参考——用于记录QGIS库中的类。 Pythonic QGIS API（pyqgis）几乎与C ++ API相同。 学习如何执行常见任务的一个好办法——是从插件仓库下载现有插件并学习它们的代码。
1.1 在Python控制台中编写脚本
QGIS为脚本编写提供了一个集成的python控制台。可以从插件→python控制台菜单中打开：
上面的截图说明了如何获取图层列表中当前选定的图层，并显示其ID，如果是矢量图层，还可以选择显示要素个数。对于与qgis环境的交互，有一个iface变量，它是QgisInterface的一个实例。此接口允许访问地图画布、菜单、工具栏和QGIS应用程序的其他部分。
为了方便用户，在启动控制台时将会执行以下语句（将来可以设置更多的初始命令）
from qgis.core import *
import qgis.utils对于经常使用控制台的用户，设置打开控制台的快捷方式可能很有用（在设置→键盘快捷键...）
1.2 Python插件
可以使用插件来扩展QGIS的功能。现在也可以使用Python编写插件。与C ++插件相比，主要优点是分发简单（不对每个平台进行编译）、更容易的开发。
自从引入对Python的支持以来，已经编写了许多涵盖各种功能的插件。插件安装程序允许用户轻松获取、升级和删除Python插件。有关插件和插件开发的更多信息，请参阅Python插件页面。
在Python中创建插件很简单，请参阅开发Python插件以获取详细说明。
小贴士：Python插件也可用于QGIS服务器（QGIS as OGC数据服务器），有关详细信息，请参阅QGIS Server Python插件。
1.3 QGIS启动时运行Python代码
每次QGIS启动时，都有两种不同的方法来运行Python代码。
-
创建startup.py脚本
-
将
PYQGIS_STARTUP环境变量设置为现有Python文件
1.3.1 startup.py文件
每次QGIS启动时，用户的Python主目录都会搜索名为startup.py的文件。 如果该文件存在，则由嵌入式Python解释器执行。
-
Linux：
.local/share/QGIS/QGIS3/profiles/default/python -
Windows：
AppData\Roaming\QGIS\QGIS3\profiles\default\python -
macOS：
Library/Application Support/QGIS/QGIS3/profiles/default
小贴士：默认路径取决于操作系统。要查找适合您的路径，请打开Python控制台，并运行QStandardPaths.standardLocations(QStandardPaths.AppDataLocation) 查看默认目录列表。
1.3.2 PYQGIS_STARTUP环境变量
你可以在QGIS初始化完成之前将PYQGIS_STARTUP环境变量设置为现有Python文件的路径来运行Python代码。
此代码将在QGIS初始化完成之前运行。此方法对于清理sys.path非常有用——可能存在不需要的路径，或用于隔离/加载初始环境——无需虚拟环境，例如在Mac上使用homebrew或MacPorts。
1.4 Python应用程序
为自动化流程创建脚本通常很方便。使用PyQGIS，这是完全可能的——导入qgis.core模块，初始化它，你就可以进行处理了。
或者您可能想要创建一个使用GIS功能的交互式应用程序——执行测量、将地图导出为PDF或任何其他功能。qgis.gui模块带来了各种GUI组件，最值得注意的是可以合并到应用程序中的地图画布控件——支持缩放，平移和任何其他自定义地图工具。
必须配置PyQGIS自定义应用程序或独立脚本以定位QGIS资源，例如投影信息，用于读取矢量和栅格图层的提供者等。QGIS资源通过在应用程序或脚本的开头添加几行（代码）来初始化。为自定义应用程序和独立脚本初始化QGIS的代码类似。以下提供各自的实例。
小贴士：千万不能使用qgis.py作为你的测试脚本的名称，否则Python将无法导入绑定。
1.4.1 在独立脚本中使用PyQGIS
要启动独立脚本，请在脚本开头初始化QGIS资源，类似于以下代码：
from qgis.core import *
# 提供qgis安装位置的路径(windows默认：C:\Program Files\QGIS 3.4\apps\qgis-ltr)
QgsApplication.setPrefixPath("/path/to/qgis/installation", True)
# 创建对QgsApplication的引用，第二个参数设置为False将禁用GUI
qgs = QgsApplication([], False)
# 加载提供者
qgs.initQgis()
# 在这里编写代码，加载一些图层，使用处理算法等
# 脚本完成后，调用exitQgis（）从内存中删除提供者和图层注册
qgs.exitQgis()我们首先导入qgis.core模块，然后配置前缀路径。前缀路径是安装QGIS的路径。它通过调用setPrefixPath方法在脚本中配置。第二个参数设置为True，它控制是否使用默认路径。
QGIS安装路径因平台而异，在系统中找到它的最简单方法是在QGIS中使用Python控制台运行 QgsApplication.prefixPath()并查看输出。
配置前缀路径后，我们在变量qgs中保存了一个对QgsApplication的引用。第二个参数设置为False，表示我们不打算使用GUI，因为我们正在编写一个独立的脚本。配置QgsApplication后 ，我们通过调用qgs.initQgis()方法加载QGIS数据提供者和图层注册。在QGIS初始化后，我们准备编写脚本的其余部分。最后，我们通过调用qgs.exitQgis()从内存中删除数据提供者和图层注册来结束。
1.4.2 在自定义应用程序中使用PyQGIS
在独立脚本中使用PyQGIS和自定义PyQGIS应用程序之间的唯一的区别是在实例化QgsApplication时的第二个参数。传递True而不是False，表示我们计划使用GUI。
from qgis.core import *
# 提供qgis安装位置的路径(windows默认：C:\Program Files\QGIS 3.4\apps\qgis-ltr)
QgsApplication.setPrefixPath("/path/to/qgis/installation", True)
# 创建对QgsApplication设置的引用第二个参数为True启用GUI，我们需要这样做，因为这是一个自定义应用程序
qgs = QgsApplication([], True)
# 加载提供者
qgs.initQgis()
# 在这里编写代码，加载一些图层，使用处理算法等
# 脚本完成后，调用exitQgis（）从内存中删除提供者和图层注册
qgs.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无缝集成。
写在最后：文中难免有翻译错误，欢迎您的指正。完整版翻译移步PyQGIS开发者手册-完整版