QGIS for Devs: Unterschied zwischen den Versionen

Aus Geometa Lab OST
Zur Navigation springen Zur Suche springen
(fix syntax)
 
(12 dazwischenliegende Versionen desselben Benutzers werden nicht angezeigt)
Zeile 1: Zeile 1:
<h2> Setting up a QGIS workspace</h2>
== Setting up a QGIS workspace==


<h3> IDE </h3>
=== IDE ===


The [https://code.visualstudio.com/ Visual Studio Code IDE] is a free and lightweight editor with advanced debugging tools, including extensions tailored for Python and QGIS development. It also supports version control and code formatting, making plugin development more efficient.
The [https://code.visualstudio.com/ Visual Studio Code IDE] is a free and lightweight editor with advanced debugging tools, including extensions tailored for Python and QGIS development. It also supports version control and code formatting, making plugin development more efficient.
Zeile 8: Zeile 8:
The Community Edition is free. It includes a powerful built-in debugger.
The Community Edition is free. It includes a powerful built-in debugger.


<h3> QGIS Extensions </h3>
=== QGIS Extensions ===


There is the [https://plugins.qgis.org/plugins/plugin_reloader/ Plugin Reloader] plugin to easily apply your code changes without restarting QGIS.
There is the [https://plugins.qgis.org/plugins/plugin_reloader/ Plugin Reloader] plugin to easily apply your code changes without restarting QGIS.
This greatly speeds up debugging and iteration, making development smoother.
This greatly speeds up debugging and iteration, making development smoother.


<h3> plugin development cycle </h3>
=== plugin development cycle ===
<ol>
<li>Modify the Python files of the AIAMAS plugin.</li>


<li>Save changes in VSCode or PyCharm.</li>
# Modify the Python files of the AIAMAS plugin.
# Save changes in VSCode or PyCharm.
# Use the Plugin Reloader to apply changes instantly.


<li>Use the Plugin Reloader to apply changes instantly.</li>
== Manual installation of a python plugin ==
</ol>
 
<h2> Manual installation of a python plugin </h2>


If a Python plugin is not available in the official repository, it can be manually installed as follows:
If a Python plugin is not available in the official repository, it can be manually installed as follows:
<ol>
<li>Clone the repository or create a new plugin in any directory.
<li>QGIS stores plugins by default in the <code>python/plugins</code> folder within the user-specific QGIS profile directory.
<strong> On Windows, the full path is typically: </strong>
<code>C:\Users\Username\AppData\Roaming\QGIS\QGIS3\profiles\default\python\plugins</code></li>


Replace <code>Username</code> with your actual Windows username.
# Clone the repository or create a new plugin in any directory.
# QGIS stores plugins by default in the <code>python/plugins</code> folder within the user-specific QGIS profile directory.




<li>The <code>AppData\Roaming</code> folder is hidden by default. To access it:
''' On Windows, the full path is typically: '''
<code>C:\Users\Username\AppData\Roaming\QGIS\QGIS3\profiles\default\python\plugins</code>


* Enable "Show hidden files" in Windows Explorer.
Replace <code>Username</code> with your actual Windows username.
* Alternatively, type <code>%appdata%</code> in the Explorer search bar, navigate back one level to AppData.</li>


All the QGIS plugins are stored inside the <code>default/python/plugins</code> folder.


# The <code>AppData\Roaming</code> folder is hidden by default. To access it:
* Enable "Show hidden files" in Windows Explorer.
* Alternatively, type <code>%appdata%</code> in the Explorer search bar, navigate back one level to AppData. All the QGIS plugins are stored inside the <code>default/python/plugins</code> folder.
# Create a shortcut to the cloned or created plugin in this directory, but only include the '''code folder'''. Not the entire repository. Files like<code>README.md</code> should not be included in this shortcut.


<li>Create a shortcut to the cloned or created plugin in this directory, but only include the <strong>code folder</strong>. Not the entire repository. Files like<code>README.md</code> should not be included in this shortcut.</li>
After restarting QGIS, the plugin will now appear under '''Extensions > Manage and Install Plugins > Installed.'''
</ol>
After restarting QGIS, the plugin will now appear under <strong>Extensions > Manage and Install Plugins > Installed.</strong>


<h2> Writing plugins </h2>
== Writing plugins ==


Documentation for Writing PyQGIS Plugins
Documentation for Writing PyQGIS Plugins


<strong>Python:</strong>
'''Python:'''


* [https://download.osgeo.org/qgis/doc/manual/qgis-1.1.0_coding-compilation_guide_en.pdf#page=35&zoom=100,-26,120 Writing a QGIS Plugin in Python]
* [https://download.osgeo.org/qgis/doc/manual/qgis-1.1.0_coding-compilation_guide_en.pdf# page=35&zoom=100,-26,120 Writing a QGIS Plugin in Python]
* [https://www.zimmi.cz/posts/2017/qgis-plugin-development-getting-started/ Getting started with a QGIS Plugin]
* [https://www.zimmi.cz/posts/2017/qgis-plugin-development-getting-started/ Getting started with a QGIS Plugin]
* [https://docs.qgis.org/3.34/en/docs/pyqgis_developer_cookbook/plugins/plugins.html#getting-started Structuring Python Plugins]
* [https://docs.qgis.org/3.34/en/docs/pyqgis_developer_cookbook/plugins/plugins.html# getting-started Structuring Python Plugins]
* [https://docs.qgis.org/testing/en/docs/pyqgis_developer_cookbook/ PyQGIS Developer Cookbook]
* [https://docs.qgis.org/testing/en/docs/pyqgis_developer_cookbook/ PyQGIS Developer Cookbook]


<strong>C++:</strong>
'''C++:'''
* [https://download.osgeo.org/qgis/doc/manual/qgis-1.1.0_coding-compilation_guide_en.pdf#page=9&zoom=100,-26,120 QGIS Plugins with C++ Manual]
* [https://download.osgeo.org/qgis/doc/manual/qgis-1.1.0_coding-compilation_guide_en.pdf# page=9&zoom=100,-26,120 QGIS Plugins with C++ Manual]


<strong>Other:</strong>
'''Other:'''
* [https://qgis.org/pyqgis/master/ QGIS API]
* [https://qgis.org/pyqgis/master/ QGIS API]
* [https://raw.githubusercontent.com/webgeodatavore/qgis-class-diagram/master/diagramme_principal.png API Overview/Poster by Thomas Gratier]  
* [https://raw.githubusercontent.com/webgeodatavore/qgis-class-diagram/master/diagramme_principal.png API Overview/Poster by Thomas Gratier]  
Zeile 71: Zeile 63:
* [http://gis.stackexchange.com/questions/tagged/pyqgis Community Support]
* [http://gis.stackexchange.com/questions/tagged/pyqgis Community Support]


<h2> Using the QGIS Python Console </h2>
== Using the QGIS Python Console ==


To open the Python console in QGIS:
To open the Python console in QGIS:
<ol>
<li>Navigate to <strong>Menu > Plugins</strong></li>


<li>Use the shortcut <strong>Ctrl+Alt+P</strong></li>
# Navigate to '''Menu > Plugins'''
</ol>
 
# Use the shortcut '''Ctrl+Alt+P'''


<strong>Expected Console Output:</strong>


<pre>
'''Expected Console Output:'''
Python Console
Use iface to access QGIS API interface or Type help(iface) for more info.
_
</pre>


<strong>Avoiding Crashes with QgsGeometry</strong>
Python Console
Use iface to access QGIS API interface or Type help(iface) for more info.
_
 
'''Avoiding Crashes with QgsGeometry'''


If using:
If using:
<pre>
 
geom = iface.activeLayer().selectedFeatures()[0].geometry()
geom = iface.activeLayer().selectedFeatures()[0].geometry()
</pre>
 


QGIS may crash due to a long-standing unresolved issue 777 with Python bindings.
QGIS may crash due to a long-standing unresolved issue 777 with Python bindings.
Instead, use:
Instead, use:


<pre>
  feat = iface.activeLayer().selectedFeatures()[0]
  feat = iface.activeLayer().selectedFeatures()[0]
  geom = QgsGeometry(feat.geometry())
  geom = QgsGeometry(feat.geometry())
</pre>
 
   
   
Testing:
Testing:
Zeile 109: Zeile 97:
See also e.g.  [http://www.qgistutorials.com/en/ Python Scripting (PyQGIS)].
See also e.g.  [http://www.qgistutorials.com/en/ Python Scripting (PyQGIS)].


<h2> Debugging QGIS-Plugins </h2>
== Debugging QGIS-Plugins ==


<h3> Debugging Methods </h3>
=== Debugging Methods ===


Developers can debug their QGIS plugin using different methods:
Developers can debug their QGIS plugin using different methods:


* <strong>print()</strong> for basic console output
* '''print()''' for basic console output


* <strong>[https://qgis.org/pyqgis/3.34/core/QgsMessageLog.html qgsMessageLog.logMessage()]</strong> to log messages inside QGIS
* '''[https://qgis.org/pyqgis/3.34/core/QgsMessageLog.html qgsMessageLog.logMessage()]''' to log messages inside QGIS


* <strong>[https://github.com/gruns/icecream icecream (ic())]</strong> for advanced debugging with variable inspection
* '''[https://github.com/gruns/icecream icecream (ic())]''' for advanced debugging with variable inspection


We recommend using IceCream (ic()) over print() for debugging.  
We recommend using IceCream (ic()) over print() for debugging.  
It displays variables and expressions with their values, formats data structures, and highlights output. Typing is faster, and it can optionally show the filename, line number, and function context.
It displays variables and expressions with their values, formats data structures, and highlights output. Typing is faster, and it can optionally show the filename, line number, and function context.


<h3> Remote Debugging with PyCharm(Debug Server) </h3>
=== Remote Debugging with PyCharm(Debug Server) ===


If running QGIS externally, enable remote debugging:
If running QGIS externally, enable remote debugging:
<ol>
<li> Install the PyCharm Debugger:
<pre>
pip install pydevd-pycharm
</pre>
</li>
<li> Add the following to the plugin code:
<pre>
import pydevd_pycharm
pydevd_pycharm.settrace('localhost', port=5678, stdoutToServer=True, stderrToServer=True, suspend=False)
</pre>
</li>


<li> In PyCharm, go to <strong>Run > Edit Configurations > Python Remote Debug</strong></li>
* Install the PyCharm Debugger:
pip install pydevd-pycharm
* Add the following to the plugin code:
import pydevd_pycharm
pydevd_pycharm.settrace('localhost', port=5678, stdoutToServer=True, stderrToServer=True, suspend=False)
* In PyCharm, go to '''Run > Edit Configurations > Python Remote Debug'''
* Set '''Host: localhost, Port: 5678''', then click '''Start Debugging'''


<li> Set <strong>Host: localhost, Port: 5678</strong>, then click <strong>Start Debugging</strong></li>
</ol>


<h2> Testing Plugins </h2>
== Testing Plugins ==


* Writing Uni Tests for QGIS Plugins: http://snorf.net/blog/2014/01/04/writing-unit-tests-for-qgis-python-plugins/
* Writing Uni Tests for QGIS Plugins: http://snorf.net/blog/2014/01/04/writing-unit-tests-for-qgis-python-plugins/
* Configuration for <strong>Debugging and Unit Testing of PyQGIS</strong>: See [[QGIS Plugins mit Python]].
* Configuration for '''Debugging and Unit Testing of PyQGIS''': See [[QGIS Plugins mit Python]].
* Testen von Qt-GUI Komponenten: http://www.voom.net/pyqt-qtest-example
* Testing Qt-GUI components: http://www.voom.net/pyqt-qtest-example


Using PyCharm simplifies QGIS plugin development with testing features
Using PyCharm simplifies QGIS plugin development with testing features




<h2> Publication of a Plugin </h2>
== Publication of a Plugin ==


[https://docs.qgis.org/3.34/en/docs/pyqgis_developer_cookbook/plugins/releasing.html Releasing your plugin]
[https://docs.qgis.org/3.34/en/docs/pyqgis_developer_cookbook/plugins/releasing.html Releasing your plugin]
Zeile 160: Zeile 140:
A <code>metadata.txt</code> file is essential as it contains descriptive information about the plugin. This helps users and QGIS manage and understand plugin details effectively.
A <code>metadata.txt</code> file is essential as it contains descriptive information about the plugin. This helps users and QGIS manage and understand plugin details effectively.


<h3> Requirements </h3>
=== Requirements ===


* If <code>hasProcessingProvider</code> exists, it should be mentioned in the "about" section.
* If <code>hasProcessingProvider</code> exists, it should be mentioned in the "about" section.
* Processing tools should be described in <code>description</code>, <code>about</code>, and added as a <code>tag</code>.
* Processing tools should be described in <code>description</code>, <code>about</code>, and added as a <code>tag</code>.
* The licence must be <strong>GPL 2 or 3</strong>. Does the <code>LICENSE</code> file exist in the repo? If not, add <strong>GPL 3</strong> from the template.
* The licence must be '''GPL 2 or 3'''. Does the <code>LICENSE</code> file exist in the repo? If not, add '''GPL 3''' from the template.
* The <code>homepage</code> must point to the <strong>actual</strong> website or at least the repo’s <code>README.md</code> (not just the repo itself).
* The <code>homepage</code> must point to the '''actual''' website or at least the repo’s <code>README.md</code> (not just the repo itself).


More details about a [https://www.giswiki.ch/QGIS_Plugins_mit_Python metadata.txt].
More details about a [https://www.giswiki.ch/QGIS_Plugins_mit_Python metadata.txt].


<h3>Pre-Upload Checklist </h3>
===Pre-Upload Checklist ===
* Ensure all attributes in <code>metadata.txt</code> are correct.
* Ensure all attributes in <code>metadata.txt</code> are correct.


* Increment the <strong>plugin version</strong> before uploading.
* Increment the '''plugin version''' before uploading.


* Change <strong>experimental flag</strong> if needed (set to <code>false</code> to appear in the default QGIS Plugin list).
* Change '''experimental flag''' if needed (set to <code>false</code> to appear in the default QGIS Plugin list).


* Set an <strong>icon</strong> (no strict size limit specified).
* Set an '''icon''' (no strict size limit specified).


* Remove unnecessary files (<code>*.pyc</code>, <code>.gitignore</code>, IDE-specific files, etc.).
* Remove unnecessary files (<code>*.pyc</code>, <code>.gitignore</code>, IDE-specific files, etc.).


* Use only <strong>ASCII characters</strong> in filenames (Umlauts will cause errors).
* Use only '''ASCII characters''' in filenames (Umlauts will cause errors).


* Plugin directory names cannot contain <strong>hyphens</strong>.
* Plugin directory names cannot contain '''hyphens'''.


* <strong>ZIP</strong> the plugin directory before upload.
* '''ZIP''' the plugin directory before upload.


<h3>Uploading</h3>
===Uploading===
In order to upload a plugin on the official QGIS page a OSGeo ID (user) is required (e.g. user account "geometalab").
In order to upload a plugin on the official QGIS page a OSGeo ID (user) is required (e.g. user account "geometalab").
<ol>
 
<li>The user account can be created here under sign-in: https://www.osgeo.org/</li>
# The user account can be created here under sign-in: https://www.osgeo.org/
<li>On the page [https://plugins.qgis.org/accounts/login/ login] with your OSGeo ID.</li>
# On the page [https://plugins.qgis.org/accounts/login/ login] with your OSGeo ID.
<li>The plugin (ZIP archive) can be uploaded [https://plugins.qgis.org/plugins/add/ here].
# The plugin (ZIP archive) can be uploaded [https://plugins.qgis.org/plugins/add/ here]. Check experimental field if the plugin still is experimental.
Check experimental field if the plugin still is experimental.</li>
# After uploading the plugin it won't be immediately available in the plugin list. It first has to get approved. The approval can take up to 2 weeks. Check [https://plugins.qgis.org/ How to add your plugin to this repository] for the criteria the plugin has to meet in order to get approved.
<li>After uploading the plugin it won't be immediately available in the plugin list. It first has to get approved. The approval can take up to 2 weeks. Check [https://plugins.qgis.org/ How to add your plugin to this repository] for the criteria the plugin has to meet in order to get approved.</li>
 
</ol>
== Weblinks ==
<h2> Weblinks </h2>


* [http://www.qgis.org/ QGIS Homepage] ([http://wiki.qgis.org/qgiswiki/Project_Organigram Project-Team QGIS])
* [http://www.qgis.org/ QGIS Homepage] ([http://wiki.qgis.org/qgiswiki/Project_Organigram Project-Team QGIS])

Aktuelle Version vom 28. Januar 2025, 12:48 Uhr

Setting up a QGIS workspace

IDE

The Visual Studio Code IDE is a free and lightweight editor with advanced debugging tools, including extensions tailored for Python and QGIS development. It also supports version control and code formatting, making plugin development more efficient.

PyCharm is a Python-focused alternative that is easier to configure than VSCode. The Community Edition is free. It includes a powerful built-in debugger.

QGIS Extensions

There is the Plugin Reloader plugin to easily apply your code changes without restarting QGIS. This greatly speeds up debugging and iteration, making development smoother.

plugin development cycle

  1. Modify the Python files of the AIAMAS plugin.
  2. Save changes in VSCode or PyCharm.
  3. Use the Plugin Reloader to apply changes instantly.

Manual installation of a python plugin

If a Python plugin is not available in the official repository, it can be manually installed as follows:

  1. Clone the repository or create a new plugin in any directory.
  2. QGIS stores plugins by default in the python/plugins folder within the user-specific QGIS profile directory.


On Windows, the full path is typically: C:\Users\Username\AppData\Roaming\QGIS\QGIS3\profiles\default\python\plugins

Replace Username with your actual Windows username.


  1. The AppData\Roaming folder is hidden by default. To access it:
  • Enable "Show hidden files" in Windows Explorer.
  • Alternatively, type %appdata% in the Explorer search bar, navigate back one level to AppData. All the QGIS plugins are stored inside the default/python/plugins folder.
  1. Create a shortcut to the cloned or created plugin in this directory, but only include the code folder. Not the entire repository. Files likeREADME.md should not be included in this shortcut.

After restarting QGIS, the plugin will now appear under Extensions > Manage and Install Plugins > Installed.

Writing plugins

Documentation for Writing PyQGIS Plugins

Python:

C++:

Other:

Using the QGIS Python Console

To open the Python console in QGIS:

  1. Navigate to Menu > Plugins
  1. Use the shortcut Ctrl+Alt+P


Expected Console Output: 

Python Console
Use iface to access QGIS API interface or Type help(iface) for more info.
_

Avoiding Crashes with QgsGeometry

If using: 

geom = iface.activeLayer().selectedFeatures()[0].geometry()


QGIS may crash due to a long-standing unresolved issue 777 with Python bindings. Instead, use: 

feat = iface.activeLayer().selectedFeatures()[0]
geom = QgsGeometry(feat.geometry())


Testing: geom.type(), geom.length(), geom.asPolyline() crashes if the line has three vertices, with only two vertices it returns an empty array.

See also e.g. Python Scripting (PyQGIS).

Debugging QGIS-Plugins

Debugging Methods

Developers can debug their QGIS plugin using different methods:

  • print() for basic console output

We recommend using IceCream (ic()) over print() for debugging. It displays variables and expressions with their values, formats data structures, and highlights output. Typing is faster, and it can optionally show the filename, line number, and function context.

Remote Debugging with PyCharm(Debug Server)

If running QGIS externally, enable remote debugging:

  • Install the PyCharm Debugger:
pip install pydevd-pycharm
  • Add the following to the plugin code:
import pydevd_pycharm
pydevd_pycharm.settrace('localhost', port=5678, stdoutToServer=True, stderrToServer=True, suspend=False)
  • In PyCharm, go to Run > Edit Configurations > Python Remote Debug
  • Set Host: localhost, Port: 5678, then click Start Debugging


Testing Plugins

Using PyCharm simplifies QGIS plugin development with testing features


Publication of a Plugin

Releasing your plugin

A metadata.txt file is essential as it contains descriptive information about the plugin. This helps users and QGIS manage and understand plugin details effectively.

Requirements

  • If hasProcessingProvider exists, it should be mentioned in the "about" section.
  • Processing tools should be described in description, about, and added as a tag.
  • The licence must be GPL 2 or 3. Does the LICENSE file exist in the repo? If not, add GPL 3 from the template.
  • The homepage must point to the actual website or at least the repo’s README.md (not just the repo itself).

More details about a metadata.txt.

Pre-Upload Checklist

  • Ensure all attributes in metadata.txt are correct.
  • Increment the plugin version before uploading.
  • Change experimental flag if needed (set to false to appear in the default QGIS Plugin list).
  • Set an icon (no strict size limit specified).
  • Remove unnecessary files (*.pyc, .gitignore, IDE-specific files, etc.).
  • Use only ASCII characters in filenames (Umlauts will cause errors).
  • Plugin directory names cannot contain hyphens.
  • ZIP the plugin directory before upload.

Uploading

In order to upload a plugin on the official QGIS page a OSGeo ID (user) is required (e.g. user account "geometalab").

  1. The user account can be created here under sign-in: https://www.osgeo.org/
  2. On the page login with your OSGeo ID.
  3. The plugin (ZIP archive) can be uploaded here. Check experimental field if the plugin still is experimental.
  4. After uploading the plugin it won't be immediately available in the plugin list. It first has to get approved. The approval can take up to 2 weeks. Check How to add your plugin to this repository for the criteria the plugin has to meet in order to get approved.

Weblinks

Von «https://giswiki.ch/index.php?title=QGIS_for_Devs&oldid=71104»