1. Introdução

Este documento pretende ser um tutorial e um guia de referência. Embora não liste todos os casos de uso possíveis, deve fornecer uma boa visão geral da funcionalidade principal.

É concedida a permissão para copiar, distribuir e / ou modificar este documento sob os termos da Licença de Documentação Livre GNU, Versão 1.3 ou qualquer versão posterior publicada pela Fundação de Software Livre; sem Secções Invariantes, sem textos de Capa e sem contracapa.

A cópia da licença é incluída na secção Licença de Documentação Livre GNU.

Esta licença também se aplica a todos os trechos de código deste documento.

O suporte ao Python foi introduzido pela primeira vez no QGIS 0.9. Existem várias maneiras de usar o Python no QGIS Desktop (abordado nas seções seguintes):

  • Emita comandos no console Python no QGIS

  • Crie e use complementos

  • Executar automaticamente o código Python quando o QGIS for iniciado

  • Criar algoritmos de processamento

  • Criar funções para expressões no QGIS

  • Crie aplicativos personalizados com base na API QGIS

As ligações Python também estão disponíveis para o QGIS Server, incluindo plugins Python (veja Servidor QGIS e Python) e ligações Python que podem ser usadas para incorporar o QGIS Server em um aplicativos Python.

Existe uma referência completa QGIS C++ API que documenta as classes das bibliotecas QGIS. Uma API QGIS Pythonica (pyqgis) é quase idêntica à API C++.

Outro bom recurso para aprender como realizar tarefas comuns é baixar os plugins existentes do “repositório de plugins <https://plugins.qgis.org/>`_ e examinar seu código.

1.1. Escrevendo Scripts no Terminal Python

O QGIS fornece um console Python integrado para scripts. Ele pode ser aberto no menu Complementos ► Terminal Python

../../_images/console.png

Fig. 1.4 Terminal Python QGIS

A captura de tela acima ilustra como obter a camada atualmente selecionada na lista de camadas, mostrar seu ID e, opcionalmente, se for uma camada vetorial, mostrar o número de feições. Para interação com o ambiente QGIS, existe uma variável iface, que é uma instância de QgisInterface. Essa interface permite o acesso à tela do mapa, menus, barras de ferramentas e outras partes do aplicativo QGIS.

Para conveniência do usuário, as seguintes instruções são executadas quando o terminal é iniciado (no futuro, será possível definir mais comandos iniciais)

from qgis.core import *
import qgis.utils

Para aqueles que utilizam o console frequentemente, pode ser útil definir um atalho para acionar o console (dentro de Configurações ► Atalhos do teclado…)

1.2. Complementos Python

A funcionalidade do QGIS pode ser estendida usando complementos. Os complementos podem ser escritos em Python. A principal vantagem sobre os complementos C++ é a simplicidade de distribuição (sem compilação para cada plataforma) e o desenvolvimento mais fácil.

Muitos complementos que abrangem várias funcionalidades foram escritos desde a introdução do suporte ao Python. O instalador do complemento permite aos usuários buscar, atualizar e remover facilmente os complementos do Python. Veja a página Python Plugins para obter mais informações sobre complementos e desenvolvimento de complementos.

Criar complementos no Python é simples, veja development_plugins para instruções detalhadas.

Nota

Os complementos Python também estão disponíveis para o servidor QGIS. Veja Servidor QGIS e Python para mais detalhes.

1.2.1. Plugins de processamento

Os Plugins de processamento podem ser usados para processar dados. Eles são mais fáceis de desenvolver, mais específicos e mais leves que os Plugins Python. ref:processing_plugin explica quando o uso de algoritmos de processamento é apropriado e como desenvolvê-los.

1.3. Executando o código Python quando o QGIS é iniciado

There are different methods to run Python code every time QGIS starts.

  1. Criando um script startup.py

  2. Configurando a variável de ambiente PYQGIS_STARTUP em um arquivo Python existente

  3. Specifying a startup script using the --code init_qgis.py parameter.

1.3.1. O arquivo startup.py

Every time QGIS starts, the user’s Python home directory and a list of system paths are searched for a file named startup.py. If that file exists, it is executed by the embedded Python interpreter.

The path in the user’s home directory usually is found under:

  • Linux: .local/share/QGIS/QGIS3

  • Windows: AppData\Roaming\QGIS\QGIS3

  • macOS: Library/Application Support/QGIS/QGIS3

The default system paths depend on the operating system. To find the paths that work for you, open the Python Console and run QStandardPaths.standardLocations(QStandardPaths.AppDataLocation) to see the list of default directories.

The startup.py script is executed immediately upon initializing python in QGIS, early on in the start of the application.

1.3.2. A variável de ambiente PYQGIS_STARTUP

Você pode executar código Python logo antes da inicialização do QGIS completar configurando a variável de ambiente PYQGIS_STARTUP com o caminho de um arquivo Python existente.

Esse código irá rodar antes da inicialização do QGIS ser completada. Este método é muito útil para a limpesa de sys.path, o qual pode haver caminhos indesejáveis, ou para isolar/carregar o ambiente inicial sem a necessidade de um ambiente virtual, ex: instalações homebrew ou MacPorts no Mac.

1.3.3. The --code parameter

You can provide custom code to execute as startup paramteter to QGIS. To do so, create a python file, for example qgis_init.py, to execute and start QGIS from the command line using qgis --code qgis_init.py.

Code provided via --code is executed late in the QGIS initialization phase, after the application components have been loaded.

1.3.4. Additional arguments for Python

To provide additional arguments for your --code script or for other python code that is executed, you can use the --py-args argument. Any argument coming after --py-args and before a -- arg (if present) will be passed to Python but ignored by the QGIS application itself.

In the following example, myfile.tif will be available via sys.argv in Python but will not be loaded by QGIS. Whereas otherfile.tif will be loaded by QGIS but is not present in sys.argv.

qgis --code qgis_init.py --py-args myfile.tif -- otherfile.tif

If you want access to every command line parameter from within Python, you can use QCoreApplication.arguments()

QgsApplication.instance().arguments()

1.4. Aplicações Python

Muitas vezes é útil criar scripts para automatizar processos. Com o PyQGIS, isso é perfeitamente possível — importe o módulo qgis.core , inicialize-o e você estará pronto para o processamento.

Ou você pode querer criar aplicações iterativas que utilizem funcionalidades de SIG — realizar meidições, exportar um mapa como PDF, … O módulo qgis.gui fornece vários componentes GUI, Mais notavelmente o widget de tela de mapa que pode ser incorporado ao palicativo com suporte para zoom, panorama e/ou qualquer outra ferramenta de mapa personalizada.

Aplicativos personalizados PyQGIS ou scripts independentes devem ser configurados para localizar os recursos QGIS, como informações de projeção e provedores para leitura de camadas vetoriais e raster. Os recursos QGIS são inicializados adicionando algumas linhas ao início de seu aplicativo ou script. O código para inicializar o QGIS para aplicativos personalizados e scripts independentes é semelhante. Exemplos de cada um são fornecidos abaixo.

Nota

Não utilize qgis.py como um nome para seu script. Python não será capaz de importar as ligações, pois o nome do script irá ocultá-las.

1.4.1. Usando PyQGIS em scripts autônomos

Para iniciar um script autônomo, inicialize os recursos do QGIS no início do script:

 1from qgis.core import *
 2
 3# Supply path to qgis install location
 4QgsApplication.setPrefixPath("/path/to/qgis/installation", True)
 5
 6# Create a reference to the QgsApplication.  Setting the
 7# second argument to False disables the GUI.
 8qgs = QgsApplication([], False)
 9
10# Load providers
11qgs.initQgis()
12
13# Write your code here to load some layers, use processing
14# algorithms, etc.
15
16# Finally, exitQgis() is called to remove the
17# provider and layer registries from memory
18qgs.exitQgis()

First we import the qgis.core module and configure the prefix path. The prefix path is the location where QGIS is installed on your system. It is configured in the script by calling the setPrefixPath() method. The second argument of setPrefixPath() is set to True, specifying that default paths are to be used.

O caminho de instalação do QGIS varia de acordo com a plataforma; a maneira mais fácil de encontrá-lo para seu sistema é utilizar o Escrevendo Scripts no Terminal Python de dentro do QGIS e olhar para a saída da execução:

QgsApplication.prefixPath()

After the prefix path is configured, we save a reference to QgsApplication in the variable qgs. The second argument is set to False, specifying that we do not plan to use the GUI since we are writing a standalone script. With QgsApplication configured, we load the QGIS data providers and layer registry by calling the initQgis() method.

qgs.initQgis()

With QGIS initialized, we are ready to write the rest of the script. Finally, we wrap up by calling exitQgis() to remove the data providers and layer registry from memory.

qgs.exitQgis()

1.4.2. Usando o PyQGIS em aplicativos personalizados

The only difference between Usando PyQGIS em scripts autônomos and a custom PyQGIS application is the second argument when instantiating the QgsApplication. Pass True instead of False to indicate that we plan to use a GUI.

 1from qgis.core import *
 2
 3# Supply the path to the qgis install location
 4QgsApplication.setPrefixPath("/path/to/qgis/installation", True)
 5
 6# Create a reference to the QgsApplication.
 7# Setting the second argument to True enables the GUI.  We need
 8# this since this is a custom application.
 9
10qgs = QgsApplication([], True)
11
12# load providers
13qgs.initQgis()
14
15# Write your code here to load some layers, use processing
16# algorithms, etc.
17
18# Finally, exitQgis() is called to remove the
19# provider and layer registries from memory
20qgs.exitQgis()

Agora você pode trabalhar com o QGIS API - carregar camadas e fazer algum processamento ou acender uma GUI com uma tela de mapa. As possibilidades são infinitas :-)

1.4.3. Executando aplicativos personalizados

Você precisa dizer ao seu sistema onde procurar bibliotecas QGIS e módulos Python apropriados se eles não estiverem em um local bem conhecido - caso contrário, Python reclamará:

>>> import qgis.core
ImportError: No module named qgis.core

This can be fixed by setting the PYTHONPATH environment variable. In the following commands, <qgispath> should be replaced with your actual QGIS installation path:

  • no Linux: export PYTHONPATH=/<qgispath>/share/qgis/python

  • no Windows: set PYTHONPATH=c:\<qgispath>\python

  • no macOS: export PYTHONPATH=/<qgispath>/Contents/Resources/python

Now, the path to the PyQGIS modules is known, but they depend on the qgis_core and qgis_gui libraries (the Python modules serve only as wrappers). The path to these libraries may be unknown to the operating system, and then you will get an import error again (the message might vary depending on the system):

>>> import qgis.core
ImportError: libqgis_core.so.3.2.0: cannot open shared object file:
  No such file or directory

Conserte isso adicionando os diretórios onde residem as bibliotecas QGIS ao caminho de busca do conector dinâmico:

  • no Linux: export LD_LIBRARY_PATH=/<qgispath>/lib

  • no Windows: set PATH=C:\<qgispath>\bin;C:\<qgispath>\apps\<qgisrelease>\bin;%PATH% onde <qgisrelease> deve ser substituído pelo tipo de liberação que você está visando (por exemplo, qgis-ltr, qgis, qgis-dev)

Estes comandos podem ser colocados em um roteiro de bootstrap que cuidará do início da operação. Ao implantar aplicações personalizadas usando PyQGIS, geralmente há duas possibilidades:

  • exigir que o usuário instale o QGIS antes de instalar sua aplicação. O instalador do aplicativo deve procurar por locais padrão das bibliotecas QGIS e permitir que o usuário defina o caminho se não for encontrado. Esta abordagem tem a vantagem de ser mais simples, porém requer que o usuário faça mais etapas.

  • pacote QGIS junto com sua aplicação. A liberação do aplicativo pode ser mais desafiadora e o pacote será maior, mas o usuário será salvo do fardo de baixar e instalar partes adicionais de software.

Os dois modelos de implantação podem ser misturados. Você pode fornecer um aplicativo autônomo em Windows e macOS, mas para Linux deixe a instalação de GIS a cargo do usuário e seu gerenciador de pacotes.

1.5. Technical notes on PyQt and SIP

We’ve decided for Python as it’s one of the most favoured languages for scripting. PyQGIS bindings in QGIS 3 depend on SIP and PyQt5. The reason for using SIP instead of the more widely used SWIG is that the QGIS code depends on Qt libraries. Python bindings for Qt (PyQt) are done using SIP and this allows seamless integration of PyQGIS with PyQt.