Viktigt

Översättning är en gemenskapsinsats du kan gå med i. Den här sidan är för närvarande översatt till 100.00%.

1. Introduktion

Detta dokument är avsett att vara både en handledning och en referensguide. Det innehåller inte en lista över alla möjliga användningsområden, men det ger en bra översikt över de viktigaste funktionerna.

Tillstånd ges att kopiera, distribuera och/eller modifiera detta dokument enligt villkoren i GNU Free Documentation License, version 1.3 eller någon senare version publicerad av Free Software Foundation; utan invarianta sektioner, utan texter på framsidan och utan texter på baksidan.

En kopia av licensen ingår i avsnittet GNU Free Documentation License.

Denna licens gäller även för alla kodavsnitt i detta dokument.

Stöd för Python introducerades först i QGIS 0.9. Det finns flera sätt att använda Python i QGIS Desktop (beskrivs i följande avsnitt):

Utföra kommandon i Python-konsolen inom QGIS
Skapa och använda plugins
Kör Python-kod automatiskt när QGIS startar
Skapa bearbetningsalgoritmer
Skapa funktioner för uttryck i QGIS
Skapa anpassade applikationer baserade på QGIS API

Python-bindningar finns också tillgängliga för QGIS Server, inklusive Python-plugins (se QGIS Server och Python) och Python-bindningar som kan användas för att bädda in QGIS Server i en Python-applikation.

Det finns en komplett QGIS C++ API-referens som dokumenterar klasserna från QGIS-biblioteken. The Pythonic QGIS API (pyqgis) är nästan identisk med C++ API.

En annan bra resurs för att lära sig hur man utför vanliga uppgifter är att ladda ner befintliga plugins från plugin repository och undersöka deras kod.

1.1. Skriptning i Python-konsolen 

QGIS tillhandahåller en integrerad Python-konsol för skriptning. Den kan öppnas från menyn Plugins –gt; Python Console:

../../_images/console.png — Fig. 1.11 QGIS Python-konsol

I skärmdumpen ovan illustreras hur man hämtar det lager som för närvarande är valt i lagerlistan, visar dess ID och eventuellt, om det är ett vektorlager, visar antalet funktioner. För interaktion med QGIS-miljön finns variabeln iface, som är en instans av QgisInterface. Detta gränssnitt ger tillgång till kartbilden, menyer, verktygsfält och andra delar av QGIS-programmet.

För att underlätta för användaren utförs följande kommandon när konsolen startas (i framtiden kommer det att vara möjligt att ställa in ytterligare initiala kommandon)

from qgis.core import *
import qgis.utils

För dem som använder konsolen ofta kan det vara bra att ange en genväg för att starta konsolen (inom Inställningar ► Tangentbordsgenvägar…)

1.2. Plugins för Python 

Funktionaliteten i QGIS kan utökas med hjälp av plugins. Plugins kan skrivas i Python. Den största fördelen jämfört med C++-plugins är enkel distribution (ingen kompilering för varje plattform) och enklare utveckling.

Många plugins som täcker olika funktioner har skrivits sedan Python-stödet introducerades. Med plugin-installationsprogrammet kan användare enkelt hämta, uppgradera och ta bort Python-plugins. Se sidan Python Plugins för mer information om plugins och plugin-utveckling.

Det är enkelt att skapa plugins i Python, se Utveckla Python-plugins för detaljerade instruktioner.

Observera

Python-plugins finns också tillgängliga för QGIS-servern. Se QGIS Server och Python för ytterligare information.

1.2.1. Plugins för bearbetning 

Processing Plugins kan användas för att bearbeta data. De är enklare att utveckla, mer specifika och mer lättviktiga än Python-plugins. Skriva ett Processing-plugin förklarar när det är lämpligt att använda Processing-algoritmer och hur man utvecklar dem.

1.3. Kör Python-kod när QGIS startar 

Det finns olika metoder för att köra Python-kod varje gång QGIS startar.

Skapa ett skript för startup.py
Ställa in miljövariabeln PYQGIS_STARTUP till en befintlig Python-fil
Ange ett startskript med hjälp av parametern --code init_qgis.py.

1.3.1. Filen :file:`startup.py

Varje gång QGIS startar söks användarens Python-hjemkatalog och en lista med systemsökvägar efter en fil med namnet startup.py. Om den filen finns, exekveras den av den inbäddade Python-tolken.

Sökvägen i användarens hemkatalog finns vanligtvis under:

Linux: :fil:`.local/share/QGIS/QGIS3``
Windows: AppData\Roaming\QGIS\QGIS3
macOS: Bibliotek/Applikationsstöd/QGIS/QGIS3

De förvalda systemsökvägarna beror på operativsystemet. För att hitta de sökvägar som fungerar för dig öppnar du Python Console och kör QStandardPaths.standardLocations(QStandardPaths.AppDataLocation) för att se listan över standardkataloger.

Skriptet startup.py exekveras omedelbart efter initiering av python i QGIS, tidigt i starten av programmet.

1.3.2. Miljövariabeln PYQGIS_STARTUP 

Du kan köra Python-kod precis innan QGIS-initialiseringen är klar genom att ställa in miljövariabeln PYQGIS_STARTUP till sökvägen för en befintlig Python-fil.

Denna kod kommer att köras innan QGIS-initialiseringen är klar. Den här metoden är mycket användbar för att rensa sys.path, som kan ha oönskade sökvägar, eller för att isolera/ladda den initiala miljön utan att kräva en virtuell miljö, t.ex. homebrew eller MacPorts-installationer på Mac.

1.3.3. Parametern ”-kod 

Du kan tillhandahålla anpassad kod som ska köras som startparameter för QGIS. Det gör du genom att skapa en pythonfil, till exempel qgis_init.py, för att köra och starta QGIS från kommandoraden med qgis --code qgis_init.py.

Kod som tillhandahålls via --code exekveras sent i QGIS initialiseringsfas, efter att applikationskomponenterna har laddats.

1.3.4. Ytterligare argument för Python 

För att ge ytterligare argument för ditt --code-skript eller för annan pythonkod som exekveras, kan du använda argumentet --py-args. Alla argument som kommer efter --py-args och före ett ---argument (om det finns) kommer att skickas till Python men ignoreras av QGIS-programmet självt.

I följande exempel kommer myfile.tif att vara tillgänglig via sys.argv i Python men kommer inte att laddas av QGIS. Medan otherfile.tif kommer att laddas av QGIS men finns inte i sys.argv.

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

Om du vill ha tillgång till alla kommandoradsparametrar från Python kan du använda QCoreApplication.arguments()

QgsApplication.instance().arguments()

1.4. Python-tillämpningar 

Det är ofta praktiskt att skapa skript för att automatisera processer. Med PyQGIS är detta fullt möjligt — importera modulen qgis.core, initiera den och du är redo för bearbetningen.

Eller så kanske du vill skapa en interaktiv applikation som använder GIS-funktionalitet — utföra mätningar, exportera en karta som PDF, … Modulen qgis.gui tillhandahåller olika GUI-komponenter, framför allt widgeten map canvas som kan integreras i applikationen med stöd för zoomning, panorering och/eller andra anpassade kartverktyg.

PyQGIS anpassade program eller fristående skript måste konfigureras för att lokalisera QGIS-resurserna, t.ex. projektionsinformation och providers för läsning av vektor- och rasterlager. QGIS-resurser initieras genom att lägga till några rader i början av programmet eller skriptet. Koden för att initiera QGIS för anpassade program och fristående skript är likartad. Exempel på var och en av dem ges nedan.

Observera

Använd inte qgis.py som namn på ditt skript. Python kommer inte att kunna importera bindningarna eftersom skriptets namn kommer att skugga dem.

1.4.1. Använda PyQGIS i fristående skript 

Om du vill starta ett fristående skript initialiserar du QGIS-resurserna i början av skriptet:

from qgis.core import *

# Supply path to qgis install location
QgsApplication.setPrefixPath("/path/to/qgis/installation", True)

# Create a reference to the QgsApplication.  Setting the
# second argument to False disables the GUI.
qgs = QgsApplication([], False)

# Load providers
qgs.initQgis()

# Write your code here to load some layers, use processing
# algorithms, etc.

# Finally, exitQgis() is called to remove the
# provider and layer registries from memory
qgs.exitQgis()

Först importerar vi modulen qgis.core och konfigurerar prefixsökvägen. Prefixsökvägen är den plats där QGIS är installerat på ditt system. Den konfigureras i skriptet genom att anropa metoden setPrefixPath(). Det andra argumentet i setPrefixPath() är inställt på True, vilket anger att standardsökvägar ska användas.

Installationsstigen för QGIS varierar beroende på plattform; det enklaste sättet att hitta den för ditt system är att använda Skriptning i Python-konsolen inifrån QGIS och titta på utdata från körningen:

QgsApplication.prefixPath()

När prefixsökvägen har konfigurerats sparar vi en referens till QgsApplication i variabeln qgs. Det andra argumentet är inställt på False, vilket anger att vi inte planerar att använda GUI eftersom vi skriver ett fristående skript. När QgsApplication har konfigurerats laddar vi QGIS-dataleverantörerna och lagerregistret genom att anropa metoden initQgis().

qgs.initQgis()

När QGIS har initialiserats är vi redo att skriva resten av skriptet. Slutligen avslutar vi genom att anropa exitQgis() för att ta bort dataleverantörerna och lagerregistret från minnet.

qgs.exitQgis()

1.4.2. Använda PyQGIS i egna applikationer 

Den enda skillnaden mellan Använda PyQGIS i fristående skript och en anpassad PyQGIS-applikation är det andra argumentet vid instansiering av QgsApplication. Skicka True istället för False för att ange att vi planerar att använda ett GUI.

from qgis.core import *

# Supply the path to the qgis install location
QgsApplication.setPrefixPath("/path/to/qgis/installation", True)

# Create a reference to the QgsApplication.
# Setting the second argument to True enables the GUI.  We need
# this since this is a custom application.

qgs = QgsApplication([], True)

# load providers
qgs.initQgis()

# Write your code here to load some layers, use processing
# algorithms, etc.

# Finally, exitQgis() is called to remove the
# provider and layer registries from memory
qgs.exitQgis()

Nu kan du arbeta med QGIS API - ladda lager och göra lite bearbetning eller starta upp ett GUI med en kartduk. Möjligheterna är oändliga :-)

1.4.3. Körning av anpassade applikationer 

Du måste tala om för ditt system var det ska söka efter QGIS-bibliotek och lämpliga Python-moduler om de inte finns på en välkänd plats - annars kommer Python att klaga:

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

Detta kan åtgärdas genom att ställa in miljövariabeln PYTHONPATH. I följande kommandon ska <qgispath> ersättas med din faktiska QGIS-installationssökväg:

på Linux: export PYTHONPATH=/<qgispath>/share/qgis/python
på Windows: set PYTHONPATH=c:\<qgispath>\python
på macOS: export PYTHONPATH=/<qgispath>/Contents/Resources/python

Nu är sökvägen till PyQGIS-modulerna känd, men de är beroende av biblioteken qgis_core och qgis_gui (Python-modulerna fungerar bara som omslag). Sökvägen till dessa bibliotek kan vara okänd för operativsystemet, och då kommer du att få ett importfel igen (meddelandet kan variera beroende på system):

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

Åtgärda detta genom att lägga till de kataloger där QGIS-biblioteken finns i sökvägen för den dynamiska länkaren:

på Linux: export LD_LIBRARY_PATH=/<qgispath>/lib
på Windows: set PATH=C:\<qgispath>\bin;C:\<qgispath>\apps\<qgisrelease>\bin;%PATH% där <qgisrelease> ska ersättas med den typ av utgåva du riktar dig till (t.ex. qgis-ltr, qgis, qgis-dev)

Dessa kommandon kan läggas in i ett bootstrap-skript som tar hand om uppstarten. När du distribuerar anpassade applikationer med PyQGIS finns det vanligtvis två möjligheter:

kräva att användaren installerar QGIS innan han/hon installerar din applikation. Installationsprogrammet för programmet bör leta efter standardplatser för QGIS-bibliotek och låta användaren ange sökvägen om den inte hittas. Den här metoden har fördelen att den är enklare, men den kräver att användaren gör fler steg.
paketera QGIS tillsammans med din applikation. Det kan vara svårare att släppa applikationen och paketet blir större, men användaren slipper ladda ner och installera ytterligare program.

De två driftsättningsmodellerna kan blandas. Du kan tillhandahålla en fristående applikation för Windows och macOS, men för Linux kan du låta användaren och dennes pakethanterare sköta installationen av GIS.

1.5. Tekniska anvisningar om PyQt och SIP 

Vi har valt Python eftersom det är ett av de mest populära språken för skript. PyQGIS-bindningar i QGIS 3 är beroende av SIP och PyQt5. Anledningen till att SIP används i stället för det mer allmänt använda SWIG är att QGIS-koden är beroende av Qt-bibliotek. Python-bindningar för Qt (PyQt) görs med SIP och detta möjliggör sömlös integration av PyQGIS med PyQt.