16.4. Configurações de IDE para gravar e depurar complementos

Embora cada programador tenha seu editor preferido de IDE/Texto, aqui estão algumas recomendações para configurar IDE populares para escrever e depurar complementos QGIS Python.

16.4.1. Complementos úteis para escrever complementos Python

Alguns complementos são convenientes ao escrever complementos Python. De Complmentos ► Gerenciar e instalar complementos…, instale:

  • Recarregador de complementos: permite recarregar um complemento e obter novas alterações sem reiniciar o QGIS.

  • Primeiros Socorros: Isso adicionará um console Python e um depurador local para inspecionar variáveis ​​quando uma exceção é gerada a partir de umcomplemento.

Aviso

Despite our constant efforts, information beyond this line may not be updated for QGIS 3. Refer to https://qgis.org/pyqgis/master for the python API documentation or, give a hand to update the chapters you know about. Thanks.

16.4.2. Uma observação sobre como configurar seu IDE no Linux e Windows

No Linux, tudo o que geralmente precisa ser feito é adicionar os locais da biblioteca QGIS à variável de ambiente PYTHONPATH do usuário. Na maioria das distribuições, isso pode ser feito editando file:~/.bashrc ou ~/.bash-profile com a seguinte linha (testada no OpenSUSE Tumbleweed):

export PYTHONPATH="$PYTHONPATH:/usr/share/qgis/python/plugins:/usr/share/qgis/python"

Salve o arquivo e implemente as configurações do ambiente usando o seguinte comando shell:

source ~/.bashrc

No Windows, você precisa ter as mesmas configurações de ambiente e usar as mesmas bibliotecas e intérpretes do QGIS. A maneira mais rápida de fazer isso é modificar o arquivo de lote de inicialização do QGIS.

Se você usou o Instalador do OSGeo4W, poderá encontrá-lo na pasta bin da sua instalação do OSGeo4W. Procure algo como C:\OSGeo4W\bin\qgis-unstable.bat.

16.4.3. Depurando usando o Pyscripter IDE (Windows)

Para usar o Pyscripter IDE, aqui está o que você deve fazer:

  1. Faça uma cópia de qgis-unstable.bat e renomeie-o como pyscripter.bat.

  2. Abra-o em um editor. E remova a última linha, a que inicia o QGIS.

  3. Adicione uma linha que aponte para o seu executável Pyscripter e adicione o argumento da linha de comando que define a versão do Python a ser usada

  4. Adicione também o argumento que aponta para a pasta em que o Pyscripter pode encontrar a dll Python usada pelo QGIS; você pode encontrá-lo na pasta bin da instalação do OSGeoW

    @echo off
SET OSGEO4W_ROOT=C:\OSGeo4W
call "%OSGEO4W_ROOT%"\bin\o4w_env.bat
call "%OSGEO4W_ROOT%"\bin\gdal16.bat
@echo off
path %PATH%;%GISBASE%\bin
Start C:\pyscripter\pyscripter.exe --python25 --pythondllpath=C:\OSGeo4W\bin

  5. Agora, quando você clicar duas vezes nesse arquivo em lote, o Pyscripter será iniciado, com o caminho correto.

Mais popular que o Pyscripter, o Eclipse é uma escolha comum entre os desenvolvedores. Na seção a seguir, explicaremos como configurá-lo para desenvolver e testar complementos.

16.4.4. Depurando usando Eclipse e PyDev

16.4.4.1. Instalação

Para usar o Eclipse, verifique se você instalou o seguinte

  • Eclipse

  • Aptana Studio 3 Plugin or PyDev

  • QGIS 2.x

  • Você também pode instalar o Remote Debug, um complemento QGIS. No momento, ainda é experimental, então habilite checkbox Complementos experimentais em Complementos ► Gerenciar e Instalar Complementos… ► Opções de antemão.

Para preparar seu ambiente para usar o Eclipse no Windows, você também deve criar um arquivo em lotes e usá-lo para iniciar o Eclipse:

  1. Localize a pasta em que a qgis_core.dll fica. Normalmente, este é C:\OSGeo4W\apps\qgis\bin, mas se você compilou seu próprio aplicativo QGIS, vai estar em sua pasta de compilação output/bin/RelWithDebInfo

  2. Encontre o executável eclipse.exe.

  3. Crie o script a seguir e use-o para iniciar o eclipse ao desenvolver complementos QGIS.

    call "C:\OSGeo4W\bin\o4w_env.bat"
set PATH=%PATH%;C:\path\to\your\qgis_core.dll\parent\folder
start /B C:\path\to\your\eclipse.exe

16.4.4.2. Configurando o Eclipse

  1. No Eclipse, crie um novo projeto. Você pode selecionar Projeto Geral e vincular suas fontes reais mais tarde, para que realmente não importe onde você coloca esse projeto.

    ../../../_images/eclipsenewproject.png

    Fig. 16.10 Projeto Eclipse

  2. Clique com o botão direito do mouse no seu novo projeto e escolha Novo ► Pasta.

  3. Clique em Avançado e escolha Link para local alternativo (pasta vinculada). Caso você já tenha fontes que deseja depurar, escolha estas. Caso contrário, crie uma pasta como já foi explicado.

Agora, na exibição Project Explorer, sua árvore de fontes é exibida e você pode começar a trabalhar com o código. Você já possui destaque de sintaxe e todas as outras ferramentas IDE poderosas disponíveis.

16.4.4.3. Configurando o depurador

Para fazer o depurador funcionar:

  1. Alterne para a perspectiva Debug no Eclipse (Janela ► Abrir Perspectiva ► Outro ► Depurar).

  2. inicie o servidor de depuração do PyDev escolhendo PyDev ► Iniciar Servidor de Depuração.

  3. Agora, o Eclipse está aguardando uma conexão do QGIS com seu servidor de depuração e, quando o QGIS se conectar ao servidor de depuração, permitirá que ele controle os scripts python. Foi exatamente para isso que instalamos o complemento Remote Debug. Portanto, inicie o QGIS, caso ainda não o tenha, e clique no símbolo de bug.

Agora você pode definir um ponto de interrupção e, assim que o código o atingir, a execução será interrompida e você poderá inspecionar o estado atual do seu complemento. (O ponto de interrupção é o ponto verde na imagem abaixo, defina um clicando duas vezes no espaço em branco à esquerda da linha em que você deseja definir o ponto de interrupção).

../../../_images/breakpoint.png

Fig. 16.11 Ponto de interrupção

Uma coisa muito interessante que você pode usar agora é o console de depuração. Certifique-se de que a execução esteja atualmente parada em um ponto de interrupção, antes de continuar.

  1. Abra a visualização Console (Janela ► Mostrar visualização). Ele mostrará o console Servidor de Depuração que não é muito interessante. Mas existe um botão Abrir Console que permite mudar para um console de depuração PyDev mais interessante.

  2. Clique na seta ao lado do botão Abrir Console e escolha PyDev Console. Uma janela se abre para perguntar qual console você deseja iniciar.

  3. Escolha Console de Depuração do PyDev. Caso esteja acinzentado e diga para você iniciar o depurador e selecionar o quadro válido, verifique se o depurador remoto está conectado e se está atualmente em um ponto de interrupção.

    ../../../_images/console-buttons.png

    Fig. 16.12 Console de Depuração do PyDev

Agora você tem um console interativo que permite testar todos os comandos do contexto atual. Você pode manipular variáveis ​​ou fazer chamadas de API ou o que quiser.

Dica

Um pouco chato é que, toda vez que você digita um comando, o console volta ao servidor de depuração. Para interromper esse comportamento, você pode clicar no botão Pin Console quando estiver na página Debug Server e ela deve se lembrar dessa decisão pelo menos para a sessão de depuração atual.

16.4.4.4. Fazendo o eclipse entender a API

Um recurso muito útil é que o Eclipse realmente saiba sobre a API QGIS. Isso permite verificar seu código quanto a erros de digitação. Mas não é só isso, também permite que o Eclipse o ajude no preenchimento automático das importações para chamadas de API.

Para fazer isso, o Eclipse analisa os arquivos da biblioteca QGIS e obtém todas as informações disponíveis. A única coisa que você precisa fazer é dizer ao Eclipse onde encontrar as bibliotecas.

  1. Clique em Janela ► Preferências ► PyDev ► Intérprete ► Python.

    Você verá seu interpretador python configurado na parte superior da janela (no momento python2.7 para QGIS) e algumas guias na parte inferior. As guias interessantes para nós são Libraries e Forced Builtins.

    ../../../_images/interpreter-libraries.png

    Fig. 16.13 Console de Depuração do PyDev

  2. Primeiramente abra a guia Libraries.

  3. Adicione uma nova pasta e escolha a pasta python da sua instalação do QGIS. Se você não souber onde está essa pasta (não é a pasta plugins):

    1. Abra o QGIS

    2. Inicie um console python

    3. Entre qgis

    4. e pressione Enter. Ele mostrará qual módulo QGIS ele usa e seu caminho.

    5. Retire o caminho /qgis/__init__.pyc deste caminho e você terá o caminho que está procurando.

  4. Você também deve adicionar sua pasta de complementos aqui (está em python/plugins na pasta user profile).

  5. Em seguida, pule para a guia Forced Builtins, clique em Novo… e digite qgis. Isso fará com que o Eclipse analise a API QGIS. Você provavelmente também deseja que o Eclipse conheça a API PyQt. Portanto, adicione também PyQt como forced builtin. Provavelmente, isso já deve estar presente na sua guia de bibliotecas.

  6. Clique em OK e pronto.

Nota

Toda vez que a API do QGIS for alterada (por exemplo, se você estiver compilando o mestre do QGIS e o arquivo SIP for alterado), volte a esta página e clique em Aplicar. Isso permitirá que o Eclipse analise todas as bibliotecas novamente.

16.4.5. Depurando com PyCharm no Ubuntu com um QGIS compilado

PyCharm é um IDE para Python desenvolvido pela JetBrains. Existe uma versão gratuita chamada Community Edition e uma paga, chamada Professional. Você pode fazer o download do PyCharm no website: https://www.jetbrains.com/pycharm/download

Estamos assumindo que você compilou o QGIS no Ubuntu com o diretório de compilação fornecido ~/dev/qgis/build/master. Não é obrigatório ter um QGIS auto-compilado, mas apenas isso foi testado. Os caminhos devem ser adaptados.

  1. No PyCharm, em seu Propriedades do Projeto, Interpretador do Projeto, criaremos um ambiente virtual Python chamado QGIS.

  2. Clique na engrenagem pequena e depois Adicionar.

  3. Selecione Virtualenv environment.

  4. Select a generic location for all your Python projects such as ~/dev/qgis/venv because we will use this Python interpreter for all our plugins.

  5. Choose a Python 3 base interpreter available on your system and check the next two options Inherit global site-packages and Make available to all projects.

../../../_images/pycharm-add-venv.png

  1. Click OK, come back on the small gear and click Show all.

  2. In the new window, select your new interpreter QGIS and click the last icon in the vertical menu Show paths for the selected interpreter.

  3. Finally, add the following absolute path to the list ~/dev/qgis/build/master/output/python.

../../../_images/pycharm-adding-path.png

  1. Restart PyCharm and you can start using this new Python virtual environment for all your plugins.

PyCharm will be aware of the QGIS API and also of the PyQt API if you use Qt provided by QGIS like from qgis.PyQt.QtCore import QDir. The autocompletion should work and PyCharm can inspect your code.

In the professional version of PyCharm, remote debugging is working well. For the Community edition, remote debugging is not available. You can only have access to a local debugger, meaning that the code must run inside PyCharm (as script or unittest), not in QGIS itself. For Python code running in QGIS, you might use the First Aid plugin mentioned above.

16.4.6. Debugging using PDB

If you do not use an IDE such as Eclipse or PyCharm, you can debug using PDB, following these steps.

  1. First add this code in the spot where you would like to debug

    # Use pdb for debugging
import pdb
# also import pyqtRemoveInputHook
from qgis.PyQt.QtCore import pyqtRemoveInputHook
# These lines allow you to set a breakpoint in the app
pyqtRemoveInputHook()
pdb.set_trace()

  2. Then run QGIS from the command line.

    On Linux do:

    $ ./Qgis

    On macOS do:

    $ /Applications/Qgis.app/Contents/MacOS/Qgis

  3. And when the application hits your breakpoint you can type in the console!

TODO:

Add testing information