1. はじめに¶

この文書は、チュートリアルとリファレンスガイドの両方を意図して書かれています。可能な事例をすべて網羅しているわけではありませんが、主要な機能を概観するには役に立つはずです。

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.

A copy of the license is included in the section GNUフリー文書利用許諾契約書.

This license also applies to all code snippets in this document.

Pythonコンソールでのスクリプティング
Python プラグイン
Running Python code when QGIS starts
- startup.py ファイル
- The PYQGIS_STARTUP environment variable
Python アプリケーション
Technical notes on PyQt and SIP

PythonのサポートはQGIS 0.9で初めて導入されました。デスクトップ版QGISでPythonを利用するのにはいくつかの方法があります（この後のセクションで説明します）。

QGISに付属するPytonコンソールでのコマンドの実行
プラグインの作成と利用
QGIS起動時のPythonコードの自動実行
プロセシングアルゴリズムの作成
QGISの「式」で使用する関数の作成
QGIS APIを利用するカスタムアプリケーションの作成

QGISサーバでもPythonプラグインを含むPythonバインディングが提供されています(参照 QGIS Server and Python) そしてPythonバインディングを使うことによってPythonアプリケーションにQGSサーバを埋め込むこともできます。

QGISライブラリのクラスのドキュメントである完全なQGIS C++ API リファレンスがあります。 Python用の QGIS API（pyqgis）はC ++ APIとほぼ同じです。

頻出タスクの実行方法を学習するには、プラグインのリポジトリから既存のプラグインをダウンロードして、そのコードを研究するのもよい方法です。

1.1. Pythonコンソールでのスクリプティング ¶

QGIS はスクリプティングのための Python console を内蔵しています。プラグイン ► Pythonコンソールメニューから開くことができます。

図 1.4 QGIS Python コンソール¶

上のスクリーンショットは、レイヤリストで現在選択されているレイヤを取得し、その ID を表示し、オプションでベクタレイヤの場合は地物数を表示する方法を示しています。QGIS 環境とのやりとりのために、 QgisInterface のインスタンスである iface 変数があります。このインタフェースにより、地図キャンバス、メニュー、ツールバー、および QGIS アプリケーションのその他の部分へのアクセスが可能になります。

ユーザーの便宜のために、コンソールの起動時に次のステートメントが実行されます（将来的にはさらに初期コマンドを設定できるようになります）

from qgis.core import *
import qgis.utils

コンソールを頻繁に使用する場合は、コンソールを起動するためのショートカットを設定すると便利な場合があります（設定->キーボードショートカット... 内）

1.2. Python プラグイン ¶

QGISの機能はプラグインを使って拡張することができます。プラグインはPythonで書くことができます。C++プラグインに比較しての主要な利点は配布の単純さ（プラットフォームごとにコンパイルする必要がありません）と開発の容易さです。

様々な機能をカバーする多くのプラグインがPythonサポートが導入されてから書かれました。プラグインのインストーラはPythonプラグインの取得、アップグレード、削除を簡単に行えます。プラグインとプラグイン開発の詳細については、 Pythonプラグインページを参照してください。

Pythonでプラグインを作るのはとても簡単です。詳細は Pythonプラグインを開発するを見てください。

注釈

PythonプラグインはQGISサーバーでも使うことができます。より詳しくは QGIS Server and Python をご覧ください。

1.3. Running Python code when QGIS starts ¶

QGISを起動するたびにPythonコードを実行するには、2つの異なる方法があります。

Creating a startup.py script
Setting the PYQGIS_STARTUP environment variable to an existing Python file

1.3.1. `startup.py` ファイル ¶

Every time QGIS starts, the user's Python home directory

Linux: .local/share/QGIS/QGIS3
Windows: AppData\Roaming\QGIS\QGIS3
macOS: Library/Application Support/QGIS/QGIS3

is searched for a file named startup.py. If that file exists, it is executed by the embedded Python interpreter.

注釈

デフォルトパスはオペレーティングシステムによって異なります。ご自身の環境に合ったパスを見つけるには、Pythonコンソールを開いて QStandardPaths.standardLocations(QStandardPaths.AppDataLocation) を実行し、デフォルトディレクトリのリストを見てください。

1.3.2. The PYQGIS_STARTUP environment variable ¶

You can run Python code just before QGIS initialization completes by setting the PYQGIS_STARTUP environment variable to the path of an existing Python file.

このコードは、QGISの初期化が完了する前に実行されます。この方法は、望ましくないパスが含まれている可能性のあるsys.pathをクリーンアップする場合や、仮想環境を必要とせずに初期環境を分離/ロードする場合に非常に役立ちます。 homebrewまたはMacPortsはMacにインストールされます。

1.4. Python アプリケーション ¶

多くの場合、プロセスを自動化するためのスクリプトを作成すると便利です。 PyQGISを使用すると、これは完全に可能です--- qgis.core モジュールをインポートし、初期化すると、処理の準備が整います。

Oまたは、GIS機能を使用するインタラクティブなアプリケーションを作成することもできます---測定を実行し、地図をPDFとしてエクスポートします...。 qgis.gui モジュールではさまざまなGUIコンポーネントを提供します。特に地図キャンバスウィジェットは、ズーム、パン、その他のカスタムの地図ツールをサポートしてアプリケーションに組み込むことができます。

PyQGISカスタムアプリケーションやスタンドアロンスクリプトは、ベクタレイヤーとラスタレイヤーを読み取るための投影情報やプロバイダーなどのQGISリソースを見つけるように構成する必要があります。 QGISリソースは、アプリケーションまたはスクリプトの先頭に数行を追加することで初期化されます。カスタムアプリケーションとスタンドアロンスクリプトのQGISを初期化するコードは似ています。それぞれの例を以下に示します。

注釈

Do not use qgis.py as a name for your script. Python will not be able to import the bindings as the script's name will shadow them.

1.4.1. スタンドアロンスクリプトでPyQGISを使用する ¶

To start a standalone script, initialize the QGIS resources at the beginning of the script:

from qgis.core import *

# Supply path to qgis install location
QgsApplication.setPrefixPath("/path/to/qgis/installation", True)

# Create a reference to the QgsApplication.  Setting the
# second argument to False disables the GUI.
qgs = QgsApplication([], False)

# Load providers
qgs.initQgis()

# Write your code here to load some layers, use processing
# algorithms, etc.

# Finally, exitQgis() is called to remove the
# provider and layer registries from memory
qgs.exitQgis()

まず、 qgis.core モジュールをインポートし、プレフィックスパスを設定します。プレフィックスパスは、QGISがシステムにインストールされている場所です。 setPrefixPath() メソッドを呼び出すことでスクリプトで構成されます。 setPrefixPath() の2番目の引数はis set to True に設定されます。これはデフォルトのパスが使用されることを指定しています。

QGISのインストールパスはプラットフォームによって異なります。お手元のシステムに対するインストールパスを見つける最も簡単な方法は、QGIS内から Pythonコンソールでのスクリプティングを使用し、実行からの出力を見ることです：

QgsApplication.prefixPath()

プレフィックスパスを設定した後、 QgsApplication への参照を変数 qgs に保存します。 2番目の引数は False に設定され、スタンドアロンスクリプトを記述しているため、GUIを使用する予定がないことを指定します。 QgsApplication を設定した状態で、 initQgis() メソッドを呼び出してQGISデータプロバイダとレイヤーレジストリをロードします。

qgs.initQgis()

QGISが初期化されたら、残りのスクリプトを書く準備ができています。最後に、 exitQgis() を呼び出して、データプロバイダとレイヤーレジストリをメモリから削除して終了します。

qgs.exitQgis()

1.4.2. カスタムアプリケーションでPyQGISを使用する ¶

スタンドアロンスクリプトでPyQGISを使用するとカスタムPyQGISアプリケーションが違うのは、 QgsApplication <qgis.core.QgsApplication> `をインスタンス化するときの2番目の引数だけです。 :const:`False の代わりに True を渡して、GUIを使用する予定であることを示します。

from qgis.core import *

# Supply the path to the qgis install location
QgsApplication.setPrefixPath("/path/to/qgis/installation", True)

# Create a reference to the QgsApplication.
# Setting the second argument to True enables the GUI.  We need
# this since this is a custom application.

qgs = QgsApplication([], True)

# load providers
qgs.initQgis()

# Write your code here to load some layers, use processing
# algorithms, etc.

# Finally, exitQgis() is called to remove the
# provider and layer registries from memory
qgs.exitQgis()

Now you can work with the QGIS API - load layers and do some processing or fire up a GUI with a map canvas. The possibilities are endless :-)

1.4.3. カスタムアプリケーションを実行する ¶

You need to tell your system where to search for QGIS libraries and appropriate Python modules if they are not in a well-known location - otherwise Python will complain:

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

This can be fixed by setting the PYTHONPATH environment variable. In the following commands, <qgispath> should be replaced with your actual QGIS installation path:

on Linux: export PYTHONPATH=/<qgispath>/share/qgis/python
on Windows: set PYTHONPATH=c:\<qgispath>\python
on 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

Fix this by adding the directories where the QGIS libraries reside to the search path of the dynamic linker:

on 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のパッケージを配布する方法です。アプリケーションのリリースにはいろいろやることがあるし、パッケージも大きくなりますが、ユーザーが追加ソフトウェアをダウンロードしてインストールするという負荷を避けられるでしょう。

2つの展開モデルを混在させることができます。 WindowsとmacOSでスタンドアロンアプリケーションを提供できますが、Linuxの場合、GISのインストールはユーザーとそのパッケージマネージャに任せます。

1.5. Technical notes on PyQt and SIP ¶

Pythonは、スクリプト作成に最も好まれる言語の1つであるため、Pythonを選択しました。 QGIS 3のPyQGISバインディングは、SIPとPyQt5に依存しています。より広く使用されているSWIGの代わりにSIPを使用する理由は、QGISコードがQtライブラリに依存しているためです。 Qt（PyQt）のPythonバインディングはSIPを使用して行われ、これによりPyQGISとPyQtのシームレスな統合が可能になります。