3. PyQGIS 쿡북 코드 작성

PyQGIS 개발자 쿡북 의 일부를 업데이트하거나 추가하려 한다면, 코드 조각을 자동적으로 테스트할 수 있도록 해주는 규칙 몇 가지를 따라야 합니다.

테스트 작업은 매우 중요합니다. 코드를 자동 확인해주는 과정이기 때문입니다. 오류가 있는 코드 조각 또는 구식 메소드를 사용하는 코드는 테스트를 통과하지 못 하고, 작성자가 문제점을 수정하도록 도와줄 알림이 뜰 것입니다.

테스트 작업을 위해, Sphinx 문서 테스트 확장 기능 을 사용합니다. 더 자세한 내용을 알고 싶다면 확장 기능 문서를 참조하세요.

3.1. 테스트 가능한 코드 조각 작성 방법

테스트 가능한 코드 조각을 작성하는 것은 구식 방법과 크게 다르지 않습니다. 기본적으로, 다른 Sphinx 지시어(directive) 를 이용해야 합니다.

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()

예시 코드를 작성한 다음, 코드를 평가하고 자동으로 실행될 몇몇 언명(assertion) 을 추가해야 합니다.

앞의 예시에서, 작성자는 좌표계를 생성하고 assert crs.isValid() 로 좌표계가 무결한지 테스트 합니다. 코드의 파이썬 문법이 틀렸거나 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. 그룹화 테스트

각 reST 문서마다, 코드 조각들을 연속해서 테스트합니다. 즉 일련의 모든 코드 조각에 대해 하나의 .. testsetup:: 을 사용할 수 있고, 그후 코드 조각들이 문서 앞부분에 선언된 변수들에 접근할 것이라는 뜻입니다.

아니면, 동일한 페이지에 있는 예시들을 그룹으로 분리해서 개별적으로 테스트를 실행할 수도 있습니다.

그룹에 코드 조각을 추가하려면 각각의 지시어에 (쉼표로 구분된) 하나 이상의 그룹명을 추가하면 됩니다.

.. 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. 사용자 로컬 환경에서 코드 조각을 테스트하는 방법

참고

다음은 리눅스 시스템에서 유효한 지침입니다.

파이썬 코드 조각을 테스트하려면, QGIS 가 설치되어 있어야 합니다. 다음과 같은 여러 가지 옵션이 있습니다:

  • 파이썬 가상 환경에서 Sphinx 와 함께 설치된 사용자 시스템의 QGIS 를 사용할 수 있습니다:

    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. 그 다음, 대상 doctest 를 실행하는 데 사용하십시오:

      make -f user.mk doctest

  • 공식 QGIS 도커 이미지 내부에서 대상 doctest 를 실행할 수 있습니다:

    make -f docker.mk doctest

    먼저 도커(docker) 를 설치해야 합니다. 이 방법은 QGIS를 내장한 도커 이미지를 사용하기 때문입니다.