Ejercicio 9: Mi primer complemento de QGIS

En los ejercicios anteriores creaste herramientas de procesamiento (un solo archivo .py). Este ejercicio es distinto: es un complemento (plugin) completo, una carpeta con varios archivos que agrega un botón y un menú a QGIS y abre una ventana propia. El complemento se llama "Complemento de prueba" y fue generado con Plugin Builder siguiendo los pasos de la página Fundamentos de complementos.

Plugin Builder escribe casi todo el código por ti. Por eso, lo más importante al estudiar este ejercicio es distinguir qué es código generado automáticamente y qué partes personalizó el creador. En los bloques de código de esta página esas partes aparecen destacadas:

Franja amarilla · Personalizado por el creador. Datos que el creador escribió en el formulario de Plugin Builder: nombres, descripción, autoría, texto del menú, etc.
Franja azul · Modificado después de generar la plantilla. Cambios hechos a mano sobre los archivos que Plugin Builder produjo (por ejemplo, un elemento agregado en Qt Designer).

Nota: las franjas se identificaron comparando los archivos con la plantilla estándar que genera Plugin Builder (tipo Tool button with dialog). Todo lo que no tiene franja es código de la plantilla que no fue alterado.

Conceptos clave de POO, PyQGIS y PyQt usados en el ejercicio

Una clase que no hereda de una clase de QGIS: class ComplementoPrueba: no tiene nada entre paréntesis. QGIS no exige herencia aquí; solo exige que la clase tenga los métodos initGui y unload. Es un ejemplo de que en POO una clase puede cumplir un "contrato" sin heredar de otra.
Herencia múltiple: class ComplementoPruebaDialog(QtWidgets.QDialog, FORM_CLASS) hereda de dos clases a la vez: QDialog (una ventana de diálogo de Qt) y FORM_CLASS (una clase generada en el momento a partir del archivo .ui).
Constructor y super(): el método __init__ prepara el objeto al crearlo, y super().__init__(parent) ejecuta primero el constructor de la clase padre.
Atributos de instancia: self.iface, self.actions, self.menu, self.first_start y self.dlg son datos que cada objeto del complemento guarda para usarlos en sus distintos métodos.
Señales y callbacks: action.triggered.connect(callback) conecta la señal triggered (el usuario presionó el botón) con una función que se ejecutará en ese momento. Se pasa la función sin paréntesis, como referencia.
El objeto iface: es la conexión con la ventana de QGIS. Con él el complemento agrega y quita su botón y su menú.
Interfaz diseñada de forma visual: la ventana no se programa línea por línea; se dibuja en Qt Designer y queda guardada en un archivo .ui (XML) que Python carga con uic.loadUiType.

Los archivos del complemento

La carpeta complemento_pruebas contiene muchos archivos, pero solo estos 5 forman el funcionamiento esencial y se analizan en esta página:

__init__.py: punto de entrada; QGIS lo busca primero.
metadata.txt: ficha del complemento (nombre, descripción, versión, autoría...).
complemento_pruebas.py: la clase principal con la lógica del complemento.
complemento_pruebas_dialog.py: la clase de la ventana.
complemento_pruebas_dialog_base.ui: el diseño de la ventana (XML de Qt Designer).

El archivo pb_tool.cfg (configuración para desplegar el complemento) se revisa al final. El resto de la carpeta lo generó Plugin Builder y no se modificó:

icon.png: icono del botón.
Makefile, pylintrc, scripts/: automatizan compilación, revisión de estilo y traducciones.
help/ e i18n/: plantillas para documentación y traducciones.
test/: pruebas automáticas de ejemplo.
README.txt y README.html: instrucciones de lo que sigue después de generar el complemento.

Análisis y explicación de la estructura y lógica del código

Sección 1 · `init.py`: el punto de entrada

Cuando QGIS inicia, revisa la carpeta de complementos y abre el archivo __init__.py de cada uno. Este archivo solo tiene una función, pero es indispensable.

__init__.py

# -*- coding: utf-8 -*-
"""
/***************************************************************************
 ComplementoPrueba
                                 A QGIS plugin
 Este complemento es para aprender como crear mi primer complemento
 Generated by Plugin Builder: http://g-sherman.github.io/Qgis-Plugin-Builder/
                             -------------------
        begin                : 2026-09-11
        copyright            : (C) 2026 by UAEMéx
        email                : complementos_qgis@uaemex.mx
        git sha              : $Format:%H$
 ***************************************************************************/

/***************************************************************************
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 ***************************************************************************/
 This script initializes the plugin, making it known to QGIS.
"""


# noinspection PyPep8Naming
def classFactory(iface):  # pylint: disable=invalid-name
    """Load ComplementoPrueba class from file ComplementoPrueba.

    :param iface: A QGIS interface instance.
    :type iface: QgsInterface
    """
    #
    from .complemento_pruebas import ComplementoPrueba
    return ComplementoPrueba(iface)

def classFactory(iface):: QGIS busca una función con este nombre exacto y la llama una sola vez al cargar el complemento. "Factory" (fábrica) significa que su trabajo es fabricar el objeto del complemento. Recibe iface, la conexión con QGIS.
from .complemento_pruebas import ComplementoPrueba: importa la clase principal. El punto antes del nombre (.complemento_pruebas) es una importación relativa: significa "el archivo complemento_pruebas.py de esta misma carpeta". La importación está dentro de la función para que el código del complemento solo se cargue cuando QGIS lo pide.
return ComplementoPrueba(iface): crea el objeto del complemento, le entrega iface y lo devuelve a QGIS.
Personalizado: el nombre de la clase (ComplementoPrueba) y el del módulo (complemento_pruebas) son los valores Class name y Module name que el creador escribió en el formulario de Plugin Builder, igual que la descripción y la autoría del encabezado.

Sección 2 · `metadata.txt`: la ficha del complemento

No es código Python: es un archivo de texto con pares clave=valor. QGIS lo lee para mostrar el complemento en el Administrador de complementos, sin ejecutar nada de Python todavía.

metadata.txt

# This file contains metadata for your plugin.

# This file should be included when you package your plugin.# Mandatory items:

[general]
name=Complemento de prueba
qgisMinimumVersion=3.0
description=Este complemento es para aprender como crear mi primer complemento
version=0.1
author=UAEMéx
email=complementos_qgis@uaemex.mx

about=El propósito de este complemento es aprender a usar el Plugin Builder.

tracker=https://www.uaemex.mx
repository=https://www.uaemex.mx
# End of mandatory metadata

# Recommended items:

hasProcessingProvider=no
# Uncomment the following line and add your changelog:
# changelog=

# Tags are comma separated with spaces allowed
tags=analysis, raster

homepage=https://www.uaemex.mx
category=Plugins
icon=icon.png
# experimental flag
experimental=True

# deprecated flag (applies to the whole plugin, not just a single version)
deprecated=False

# Since QGIS 3.8, a comma separated list of plugins to be installed
# (or upgraded) can be specified.
# Check the documentation for more information.
# plugin_dependencies=

Category of the plugin: Raster, Vector, Database or Web
# category=

# If the plugin can run on QGIS Server.
server=False

[general]: sección del archivo. Todos los datos están dentro de ella.
name, description, about: nombre, resumen y explicación larga que se ven en el Administrador de complementos. Personalizados por el creador.
author, email: datos de autoría. Personalizados.
tracker, repository, homepage: direcciones web (reporte de errores, código fuente y página del proyecto). Personalizadas.
tags: palabras clave (analysis, raster) que ayudan a encontrar el complemento en las búsquedas. Personalizadas.
qgisMinimumVersion=3.0: versión mínima de QGIS compatible. Viene de la plantilla.
version=0.1: versión del complemento. Valor inicial de la plantilla.
hasProcessingProvider=no: indica que el complemento no agrega herramientas a la Caja de herramientas de procesos (a diferencia de los ejercicios 1 a 8).
icon=icon.png: archivo que se usa como icono.
experimental=True: marca el complemento como experimental.
deprecated=False, server=False: no está obsoleto y no está pensado para QGIS Server.
Las líneas que inician con # son comentarios con instrucciones de la plantilla; QGIS las ignora.

Sección 3 · `complemento_pruebas.py`: la clase principal

Este es el archivo con la clase del complemento. Primero se muestra completo y después se explica por partes: importaciones, constructor y cada método.

complemento_pruebas.py

# -*- coding: utf-8 -*-
"""
/***************************************************************************
 ComplementoPrueba
                                 A QGIS plugin
 Este complemento es para aprender como crear mi primer complemento
 Generated by Plugin Builder: http://g-sherman.github.io/Qgis-Plugin-Builder/
                              -------------------
        begin                : 2026-09-11
        git sha              : $Format:%H$
        copyright            : (C) 2026 by UAEMéx
        email                : complementos_qgis@uaemex.mx
 ***************************************************************************/

/***************************************************************************
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 ***************************************************************************/
"""
from qgis.PyQt.QtCore import QLocale, QTranslator, QCoreApplication
from qgis.core import QgsSettings
from qgis.PyQt.QtGui import QIcon
from qgis.PyQt.QtWidgets import QAction

# Import the code for the dialog
from .complemento_pruebas_dialog import ComplementoPruebaDialog
import os.path


class ComplementoPrueba:
    """QGIS Plugin Implementation."""

    def __init__(self, iface):
        """Constructor.

        :param iface: An interface instance that will be passed to this class
            which provides the hook by which you can manipulate the QGIS
            application at run time.
        :type iface: QgsInterface
        """
        # Save reference to the QGIS interface
        self.iface = iface
        # initialize plugin directory
        self.plugin_dir = os.path.dirname(__file__)
        # initialize locale
        locale = QgsSettings().value('locale/userLocale', QLocale().name())[0:2]
        locale_path = os.path.join(
            self.plugin_dir,
            'i18n',
            '{}.qm'.format(locale))

        if os.path.exists(locale_path):
            self.translator = QTranslator()
            self.translator.load(locale_path)
            QCoreApplication.installTranslator(self.translator)

        # Declare instance attributes
        self.actions = []
        self.menu = self.tr(u'&Complemento de prueba')

        # Check if plugin was started the first time in current QGIS session
        # Must be set in initGui() to survive plugin reloads
        self.first_start = None

    # noinspection PyMethodMayBeStatic
    def tr(self, message):
        """Get the translation for a string using Qt translation API.

        We implement this ourselves since we do not inherit QObject.

        :param message: String for translation.
        :type message: str, QString

        :returns: Translated version of message.
        :rtype: QString
        """
        # noinspection PyTypeChecker,PyArgumentList,PyCallByClass
        return QCoreApplication.translate('ComplementoPrueba', message)


    def add_action(
        self,
        icon_path,
        text,
        callback,
        enabled_flag=True,
        add_to_menu=True,
        add_to_toolbar=True,
        status_tip=None,
        whats_this=None,
        parent=None):
        """Add a toolbar icon to the toolbar.

        :param icon_path: Path to the icon for this action. Can be a resource
            path (e.g. ':/plugins/foo/bar.png') or a normal file system path.
        :type icon_path: str

        :param text: Text that should be shown in menu items for this action.
        :type text: str

        :param callback: Function to be called when the action is triggered.
        :type callback: function

        :param enabled_flag: A flag indicating if the action should be enabled
            by default. Defaults to True.
        :type enabled_flag: bool

        :param add_to_menu: Flag indicating whether the action should also
            be added to the menu. Defaults to True.
        :type add_to_menu: bool

        :param add_to_toolbar: Flag indicating whether the action should also
            be added to the toolbar. Defaults to True.
        :type add_to_toolbar: bool

        :param status_tip: Optional text to show in a popup when mouse pointer
            hovers over the action.
        :type status_tip: str

        :param parent: Parent widget for the new action. Defaults None.
        :type parent: QWidget

        :param whats_this: Optional text to show in the status bar when the
            mouse pointer hovers over the action.

        :returns: The action that was created. Note that the action is also
            added to self.actions list.
        :rtype: QAction
        """

        icon = QIcon(icon_path)
        action = QAction(icon, text, parent)
        action.triggered.connect(callback)
        action.setEnabled(enabled_flag)

        if status_tip is not None:
            action.setStatusTip(status_tip)

        if whats_this is not None:
            action.setWhatsThis(whats_this)

        if add_to_toolbar:
            # Adds plugin icon to Plugins toolbar
            self.iface.addToolBarIcon(action)

        if add_to_menu:
            self.iface.addPluginToMenu(
                self.menu,
                action)

        self.actions.append(action)

        return action

    def initGui(self):
        """Create the menu entries and toolbar icons inside the QGIS GUI."""

        icon_path = os.path.join(os.path.dirname(__file__), 'icon.png')
        self.add_action(
            icon_path,
            text=self.tr(u'Mi complemento'),
            callback=self.run,
            parent=self.iface.mainWindow())

        # will be set False in run()
        self.first_start = True


    def unload(self):
        """Removes the plugin menu item and icon from QGIS GUI."""
        for action in self.actions:
            self.iface.removePluginMenu(
                self.tr(u'&Complemento de prueba'),
                action)
            self.iface.removeToolBarIcon(action)


    def run(self):
        """Run method that performs all the real work"""

        # Create the dialog with elements (after translation) and keep reference
        # Only create GUI ONCE in callback, so that it will only load when the plugin is started
        if self.first_start == True:
            self.first_start = False
            self.dlg = ComplementoPruebaDialog()

        # show the dialog
        self.dlg.show()
        # Run the dialog event loop
        result = self.dlg.exec_()
        # See if OK was pressed
        if result:
            # Do something useful here - delete the line containing pass and
            # substitute with your code.
            pass