QGISプラグインの開発を得意分野の１つとする我々が普段 Visual Studio Code (VS Code) 上で効率良くプラグインを開発するのに欠かせないテクニックとして、今回はVS Codeのコード補完と型チェックを機能させながらプラグインを開発する方法を紹介します。
うまく設定すると、下図のように VS Code（というかPythonの言語サーバ）による支援を受けながらQGISプラグインを開発できます。控え目に言って最高です。
コード補完や引数などの情報が得られるだけでなく、型チェックや静的解析も機能するようになるため、コードの品質も少なからず良くなるでしょう。
これらのコード補完や型チェックなどが開発体験において非常に重要であることは、現代のプログラマの皆さんには説明するまでもありません（！？）。
コード補完や型ヒントを機能させる
通常、VS Code 上で QGIS プラグインを開発する際には、最重要のライブラリである PyQGIS と PyQt5 に関してコード補完が一切効かないという問題があります。これは、PyQGIS や PyQt5 が QGIS 内蔵の特別なPython環境に閉ざされており、VS Code の言語サーバがそのPython環境を自動で認識できないためです。
この問題を解決するには、VS CodeにQGIS内蔵のPython環境を認識させる必要がありますが、実はこれは Python に標準で備わっている「仮想環境」（virtual environment、venv）の仕組みを利用すれば上手く実現することができます。
なお、Pythonの venv をそのまま使っても実現できますが、我々はワークフローをシンプルにするために Poetry というパッケージ管理ツールを介して venv を使っています。Poetry の使い方や概念ついてはここでは説明しません。ごめんなさい。
以下に、Poetry を使って QGIS のPython環境をVS Codeに認識させる手順を示します。 まずは macOS での設定方法から紹介して、次に、Windows での設定方法も示します。
macOS での設定方法
プロジェクトを作りたいディレクトリ内で、以下のコマンドを実行してください：
# poetry をインストールしていない方はインストールしてください。
pip3 install poetry -U
# 仮想環境 (.venv) をプロジェクトフォルダ内に作るように設定します。
poetry config --local virtualenvs.in-project true
# QGISのPython環境に含まれているパッケージ (qgis, PyQt5 など) を
# 今回作る仮想環境 (venv) に引き継ぐ設定をします。(重要)
poetry config --local virtualenvs.options.system-site-packages true
# 新規プロジェクトをセットアップします。
poetry init
# QGIS に内蔵されたPythonを使うようにPoetryに指示します。(重要)
poetry env use /Applications/QGIS.app/Contents/MacOS/bin/python3
# 仮想環境を構築します。
poetry install
# プロセッシングフレームワークなどの特殊な QGIS 内蔵 Python パッケージを
# 認識させたい場合は以下も実行してください。
echo /Applications/QGIS.app/Contents/Resources/python/plugins > .venv/lib/python3.9/site-packages/qgis_std_plugins.pth
これで完了です。
あとは、VS Codeのコマンドパレットで "Python: Select Interpreter" を実行して、 .venv 内のPython環境を選択すればOKです。
PyQGIS や PyQt5 について、VS Code の支援を受けられるようになっているか確認してみてください。
Windows (OSGeo4W版) での設定方法
次にWindowsにおける設定方法を解説します。mac版のときとは若干違うアプローチをとります。
Windows用のQGISビルドは複数あり、構成などがそれぞれ異なります。ここでは OSGeo4W 版の QGIS LTR を例にして説明します。
コマンドプロンプトで以下の手順を実行してください。それぞれの意味はコメントを参考にしてください。
@rem QGISのPython環境を使ってPoetryをインストールします。
C:\OSGeo4W\bin\python-qgis-ltr.bat -m pip install poetry
@rem 仮想環境 (.venv) がプロジェクトフォルダ内に作られるようにします。
C:\OSGeo4W\bin\python-qgis-ltr.bat -m poetry config --local virtualenvs.in-project true
@rem QGISに含まれているパッケージを今回作る仮想環境 (venv) に引き継ぐ設定をします。
C:\OSGeo4W\bin\python-qgis-ltr.bat -m poetry config --local virtualenvs.options.system-site-packages true
@rem 仮想環境を新規に作ります
C:\OSGeo4W\bin\python-qgis-ltr.bat -m poetry init
@rem Windows用QGISには PyQt5 の型スタブが同梱されていないため、
@rem 追加でインストールします
C:\OSGeo4W\bin\python-qgis-ltr.bat -m poetry add -G dev pyqt5-stubs
@rem 仮想環境を構築します
C:\OSGeo4W\bin\python-qgis-ltr.bat -m poetry install
@rem Windows版のQGISでは、Pythonパッケージが特殊な場所に配置されているため、それらにパスを通します。
C:\OSGeo4W\bin\python-qgis-ltr.bat -c "import pathlib;import qgis;open('.venv/Lib/site-packages/qgis.pth', 'w').write(str((pathlib.Path(qgis.__file__)/'../..').resolve()) + '\n' + str((pathlib.Path(qgis.__file__)/'../../plugins').resolve()))"
これで Windows でも PyQGIS と PyQt5 のコード補完が効くようになるはずです。
追記: 参考になりそうな記事
先人の皆さんが書かれた記事を見つけたので紹介しておきます。
参考リポジトリ
弊社が開発してオープンソースライセンスで無償公開しているQGISプラグインのリポジトリでも、上述したような VS Code の支援受けるための設定を施してあります。具体的なコードを参考にしたい場合はご覧ください。
この記事で手動で行っている操作を、 Makefile で半自動化したりもしています。
↑は法務省登記所備付地図データをQGISで読み込むためのプラグインです。
今回は説明しませんでしたが、上手く設定することでQGISのPython環境を使ったテスト自動化なども実現できます。そのあたりはまた今後。