VSCodeによるQGISプラグイン開発環境の構築
概要
VSCodeを使ったQGISのプラグイン開発環境を紹介します。色々と細かい設定が必要になる部分が多いので、ここに整理しておきたいと思います。
使用環境
OS | Windows 11 | |
---|---|---|
QGIS | QGIS 本体 | 3.28.7 LTR |
Python | 3.9.5 | |
Visual Studio Code | Visual Studio Code 本体 | 1.79.0 |
Python 拡張機能 | 2023.10.0 | |
Pylance 拡張機能 | 2023.6.10 |
VSCodeでのPythonのデバッグやインテリセンスを有効化するため、以下の拡張機能もインストールしておく必要があります。
プロジェクト構成
ここでは、以下の記事で紹介したプラグインを用いてプロジェクトフォルダを作成します。
プロジェクトフォルダは以下のように構成します。プラグイン本体を構成するファイルは一つのフォルダ ./test_plugin
にまとめ、一つ上の階層に README.md
や .vscode
フォルダを配置するようにします。
📂test_plugin ├─📂.vscode │ ├─📄settings.json │ └─📄launch.json ├─📂test_plugin │ ├─📄metadata.txt │ ├─📄__init__.py │ ├─📄plugin.py │ ├─📄my_dialog.py │ └─📄my_dialog_base.ui └─📄README.md
QGIS上でプラグインを有効化するには ./test_plugin
のフォルダをプラグインフォルダにデプロイする必要がありますが、シンボリックリンクを用いてプラグインフォルダから参照するようにすると便利です。シンボリックリンクの作成は管理者権限で起動したPowerShellで以下のコマンドを実行します。-Name
や -Value
はプラグイン名やプロジェクトのディレクトリに応じて適宜変更します。
New-Item -Type SymbolicLink -Path "${env:APPDATA}\QGIS\QGIS3\profiles\default\python\plugins\" -Name "test_plugin" -Value "C:\path_to_projects\test_plugin\test_plugin"
ただし、シンボリックリンクを作成した場合、QGIS上でプラグインをアンインストールした場合、元のプロジェクトフォルダのプラグインも削除されてしまう点には注意が必要です。
インタープリターの指定
PythonインタープリターとしてQGISにバンドルされているPythonを指定し、QGISにバンドルされているパッケージに対するインテリセンスを有効化します。
VSCodeでプロジェクトフォルダを開き、任意のPythonスクリプトを開いて、右下の インタープリターの選択
をクリックします。
インタープリターパスを入力...
を選択します。
QGISにバンドルされているPythonのパス C:\Program Files\QGIS 3.28.7\apps\Python39\python.exe
を入力しEnterを押すと、インタープリターの指定は完了です。
ワークスペースの設定
プラグイン開発に適した設定を適用するため、ワークスペースの設定ファイル ./.vscode/settings.json
を以下のように記述します。
{ "python.analysis.extraPaths": [ "C:\\PROGRA~1\\QGIS32~1.7\\apps\\qgis-ltr\\python", ], "files.associations": { "metadata.txt": "ini", "*.qrc": "xml", "*.ui": "xml" }, "terminal.integrated.defaultProfile.windows": "OSGeo4W Shell", "terminal.integrated.profiles.windows": { "OSGeo4W Shell": { "path": "${env:ComSpec}", "args": [ "/k", "C:\\PROGRA~1\\QGIS32~1.7\\OSGeo4W.bat;popd", ], "icon": "terminal-cmd" } }, }
各設定のパスに使用している QGIS32~1.7
の文字列はQGISのバージョンに応じて書き換えが必要です。
各設定内容について以下で説明します。
カスタムパッケージのインテリセンスの有効化
QGISのPython APIである qgis
パッケージはインタープリターの指定だけではVSCodeから参照されません。そのため、インテリセンスを有効化するにはパッケージの保存場所をカスタムパッケージとして以下のように指定する必要があります。
"python.analysis.extraPaths": [ "C:\\PROGRA~1\\QGIS32~1.7\\apps\\qgis-ltr\\python", ],
ファイルの関連付け
プラグインに用いる専用のファイルに対してシンタックスハイライトを有効化するため、以下のようにファイル名や拡張子との関連付けを行います。
"files.associations": { "metadata.txt": "ini", "*.qrc": "xml", "*.ui": "xml" },
ターミナルでのOSGeo4W Shellの使用
プラグインによってはOSGeo4W Shellから pyrcc5
等のコマンドを実行する必要があります。このOSGeo4W ShellをVSCodeのターミナルで使用する設定を以下のように記述します。
"terminal.integrated.defaultProfile.windows": "OSGeo4W Shell", "terminal.integrated.profiles.windows": { "OSGeo4W Shell": { "path": "${env:ComSpec}", "args": [ "/k", "C:\\PROGRA~1\\QGIS32~1.7\\OSGeo4W.bat;popd", ], "icon": "terminal-cmd" } },
上記のようにターミナルの設定を記述することで、VSCodeのターミナルからOSGeo4W Shellを起動でき、pyrcc5
などのコマンドが使用可能になります。
デバッグ設定
デバッグの方法としては
の2つがあります。
デバッガーにアタッチする方法
ptvsd
や debugpy
などのVSCode用のPythonデバッガーでサーバーを起動し、そのサーバーにアタッチしてデバッグする方法です。詳細は以下のページで紹介されています。
debugpy
を使った方法についてはこちらでも詳しく解説されています。
Debugging QGIS 3.x python plugins on Windows 11 using VS Code
プラグインの開発におけるデバッガーには ptvsd
を用いる方法が主流だったようですが、VSCode用のデバッガーは ptvsd
から debugpy
に移行されており、ptvsd
の使用は現在非推奨となっています。そのため、デバッガーとしては debugpy
を使用するのが推奨されます。
この方法ではデバッガーのインストールやその他下準備が必要になるので、ここでは次に紹介するQGISにアタッチする方法でデバッグすることにします。
デバッグ時にQGISのプロセスを指定してアタッチする方法
この方法ではデバッガーによるサーバーを立てず、QGISのプロセスに直接アタッチします。別途デバッガーをインストールしたりする必要がなく、launch.json
にデバッグ設定を記述するだけなのでお手軽です。この方法は下記のページで紹介されていました。
プロセスを指定してアタッチするには、デバッグ設定ファイル ./.vscode/launch.json
に以下のように記述します。
{ "version": "0.2.0", "configurations": [ { "name": "Attach QGIS", "type": "python", "request": "attach", "processId": "${command:pickProcess}", "pathMappings": [ { "localRoot": "${workspaceFolder}/test_plugin", "remoteRoot": "${env:APPDATA}/QGIS/QGIS3/profiles/default/python/plugins/test_plugin" } ], "justMyCode": true } ] }
"processId": "${command:pickProcess}"
とすることで、デバッグ時にアタッチするプロセスが選択できるので、QGISが起動した状態でデバッグを開始し、プロセスの選択で qgis-ltr-bin.exe
を指定します。
アタッチしたのち、ブレークポイントを設定してQGISでプラグインを起動すると、正常にブレークポイントで停止することが確認できます。
また、シンボリックリンクによりプラグインフォルダにプラグインを配置している場合、編集中のスクリプトとQGISで実行されているスクリプトのパスが異なることになります。これらを同一のスクリプトとVSCodeに認識させるため、./.vscode/launch.json
にて pathMappings
を指定しています。
型ヒントの導入
前述の設定でデバッグが可能なのですが、デバッグ時にQGISとVSCodeの行き来が必要だったりデバッグの動作が重かったりするので、デバッグはここぞという時だけに絞りたいところです。デバッグに頼らずバグチェックを行うにはPylanceによる静的解析が便利で、それを活かす上で型ヒントの導入も有効です。
例えば以下のように関数の引数 iface
に対して型ヒントを行う場合、qgis.gui
から QgisInterface
クラスをインポートし、関数の引数に iface: QgisInterface
と記述します。
from qgis.gui import QgisInterface class TestPlugin: def __init__(self, iface: QgisInterface): self.iface = iface
アノテーションに利用する qgis
のクラス一覧は以下で参照できます。
このように型ヒントを記述することで、iface
の型が言語サーバーに認識され、以下のように入力補完が利用できるようになります。
また、上図の addVectorLayer()
の第三引数 providerKey
は str
型である必要がありますが、下記のように入力を誤っていた際には引数エラーが検出されます。
以上のようなVSCodeの静的解析ツールを利用することで、デバッグの実行を最小限に抑えられます。
開発したプラグインの配布
プラグインを配布する際は、./test_plugin
フォルダをそのまま圧縮することでzipパッケージになります。
Compress-Archive -Path ".\test_plugin\" -DestinationPath "test_plugin.zip" -Force
作成したzipパッケージはQGISの ZIPからインストール
にてインストール可能です。
あとがき
以上、VSCodeにおけるQGISプラグイン開発に便利な設定等を紹介しました。
QGISのプラグイン開発に限ったことではないですが、コードフォーマッタのBlackやisortも利用するとより開発が捗るのでおすすめです。