3. PyQGISクックブック中でコードを書く

PyQGIS 開発者用 Cookbook の章を追加または更新することを計画している方は、コードスニペットの自動テストを可能にするためにいくつかの規則に従ってください。

テストはコードの自動チェックを可能にするので非常に重要です。 エラーのあるコードスニペットや古いメソッドを使用するコードは失敗し、その通知は問題の解決に役立ちます。

テストのために、 Sphinx doctest拡張機能 を使います。より詳細な情報については拡張機能のドキュメントを参照してください。

3.1. テスト可能なコードスニペットの書き方

テスト可能なコードスニペットを書くことは 古い 方法とそれほど変わりません。基本的には、異なるSphinxの ディレクティブ を使う必要があります。

3.1.1. sphinxディレクティブを文書化する

コードを .. code-block:: python ディレクティブに埋め込む代わりに（そうすると自動的にコード構文が強調表示される）、今度は .. testcode:: に埋め込む必要があります。つまり、これの代わりに:

.. code-block:: python

   crs = QgsCoordinateReferenceSystem("EPSG:4326")
   assert crs.isValid()

今度はこれを使用します:

.. testcode::

   crs = QgsCoordinateReferenceSystem("EPSG:4326")
   assert crs.isValid()

サンプルコードを書いた後は、コードを評価して自動的に実行される アサーション を追加する必要があります。

上記の例では、crsを作成し、 assert crs.isValid() でそれが有効かどうかを テスト します。コードのPython構文が間違っていたり crs.isValid() が False を返した場合、このコードスニペットはテスト中に失敗します。

スニペットでテストを正しく実行するには、すべてのクラスをインポートし、コードスニペットで使用されている変数を宣言する必要があります。それらはコードスニペット自体（HTMLページに表示される）に含めることも、 .. testsetup :: ディレクティブに追加することもできます（HTMLページには表示されません）。 .. testsetup:: は .. testcode:: の前に置く必要があります:

.. testsetup::

   from qgis.core import QgsCoordinateReferenceSystem

.. testcode::

   crs = QgsCoordinateReferenceSystem("EPSG:4326")
   assert crs.isValid()

コードスニペットがオブジェクトを作成しない（したがって、 assert object.isValid() のようなものが使用できない）場合、 print() メソッドを使用してコードをテストし、期待される結果を .. testoutput :: ディレクティブ内に追加して、期待される出力を比較できます:

.. testcode::

   print("QGIS CRS ID:", crs.srsid())
   print("PostGIS SRID:", crs.postgisSrid())

.. testoutput::

   QGIS CRS ID: 3452
   PostGIS SRID: 4326

デフォルトでは、 .. testoutput:: の内容はHTML出力に表示されます。 HTMLから隠すには :hide: を使います:

.. testoutput::
   :hide:

   QGIS CRS ID: 3452
   PostGIS SRID: 4326

注釈

コードスニペットにprint文が含まれている場合は、期待される出力とともに testoutput を追加しなければなりません。そうでなければテストは失敗します。

3.1.2. テストをグループ化する

各rst 文書ごとに、コードスニペットは順番にテストされます。つまり、以下のすべてのコードスニペットに対して1つの .. testsetup:: を使用でき、後のスニペットでは文書内の前のスニペットで宣言された変数にアクセスできます。

あるいは、グループを使用して、異なるテスト中の同じページの例を分類することもできます。

それぞれのディレクティブに1つ以上のグループ名を（コンマで区切って）追加して、コードスニペットをグループに追加します:

.. testcode:: crs_crsfromID [, morenames]

   crs = QgsCoordinateReferenceSystem("EPSG:4326")
   assert crs.isValid()

doctest は各グループのスニペットを選び、それらを独立して実行します。

注釈

関連するコンテンツで意味のあるグループ名を使用してください。 <chapter>_<subchapter> のようなものを使用してください、例えばcrs_intro、crs_fromwkt。障害が発生した場合は、障害が発生した場所を特定するのに役立ちます。

グループを宣言しないと、コードスニペットは default という名前のグループに追加されます。 代わりに、グループ名として * を使用すると、スニペットはすべてのテストグループで使用されます。これは通常、テスト設定で使用すると便利です:

.. testsetup:: *

   from qgis.core import QgsCoordinateReferenceSystem

3.2. ローカルマシンでスニペットをテストする方法

注釈

インストラクションはLinuxシステムで有効です。

Pythonのコードスニペットをテストするには、QGIS のインストールが必要です。これには多くのオプションがあります。次が可能です：

  • Pythonの仮想環境から自分のシステムにインストールした QGIS を Sphinx と一緒に使用します:

    make -f venv.mk doctest

  • 手動でビルドした QGIS を使います。次を行う必要があります:

    1. venv.mk ファイルをカスタムした Makefile 拡張を作ります。例えば user.mk ファイルを以下のような内容で作成します:

      # Root installation folder
QGIS_PREFIX_PATH = /home/user/apps/qgis-master

include venv.mk

      または:

      # build output folder
QGIS_PREFIX_PATH = /home/user/dev/QGIS-build-master/output

include venv.mk

    2. 次に、それを使ってtarget doctest を実行します:

      make -f user.mk doctest

  • 公式の QGIS docker イメージ内で doctest ターゲットを実行します:

    make -f docker.mk doctest

    QGISの中にあるdockerイメージを使用するため、最初に Docker をインストールする必要があります。