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のバージョンに応じて書き換えが必要です。

各設定内容について以下で説明します。

カスタムパッケージのインテリセンスの有効化

QGISPython 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 などのコマンドが使用可能になります。

デバッグ設定

デバッグの方法としては

  • デバッガーにアタッチする方法
  • デバッグ時にQGISのプロセスを指定してアタッチする方法

の2つがあります。

デバッガーにアタッチする方法

ptvsddebugpy などの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 を指定しています。

型ヒントの導入

前述の設定でデバッグが可能なのですが、デバッグ時にQGISVSCodeの行き来が必要だったりデバッグの動作が重かったりするので、デバッグはここぞという時だけに絞りたいところです。デバッグに頼らずバグチェックを行うには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() の第三引数 providerKeystr 型である必要がありますが、下記のように入力を誤っていた際には引数エラーが検出されます。

以上のようなVSCodeの静的解析ツールを利用することで、デバッグの実行を最小限に抑えられます。

開発したプラグインの配布

プラグインを配布する際は、./test_plugin フォルダをそのまま圧縮することでzipパッケージになります。

Compress-Archive -Path ".\test_plugin\" -DestinationPath "test_plugin.zip" -Force

作成したzipパッケージはQGISZIPからインストール にてインストール可能です。

あとがき

以上、VSCodeにおけるQGISプラグイン開発に便利な設定等を紹介しました。

QGISプラグイン開発に限ったことではないですが、コードフォーマッタのBlackやisortも利用するとより開発が捗るのでおすすめです。