Tutorial Completo PyQt5: Construye GUIs Profesionales en Python

¿Qué es PyQt?

PyQt es un binding de Python para el framework Qt, una librería C++ multiplataforma usada para crear aplicaciones GUI nativas en Windows, macOS, Linux, Android, iOS, Raspberry Pi y más. El binding es mantenido por Riverbank Computing (UK), mientras que Qt es desarrollado por The Qt Company (Finlandia). PyQt da a desarrolladores Python acceso al rico conjunto de widgets, networking, base de datos, 3D y capacidades multimedia de Qt.

En este tutorial aprenderás:

• Características clave de PyQt5
• Versiones disponibles de PyQt
• Cómo instalar PyQt5 en Windows, macOS y Linux
• Conceptos fundamentales de PyQt y programas de ejemplo
• Componentes y widgets centrales
• Estrategias de layout y personalización de temas

Características Clave de PyQt5

PyQt5 expone más de 600 clases que cubren:

• Interfaces Gráficas de Usuario
• Integración SQL (SQLite, MySQL, PostgreSQL, Oracle, ODBC)
• Renderizado web vía QtWebEngine
• Parseo y manipulación XML
• Networking robusto (TCP/UDP, SSL, DNS)
• Multimedia y gráficos 3D (QtMultimedia, Qt3D)

Estas capacidades permiten construir aplicaciones desktop y embebidas complejas de alto rendimiento. Grandes corporaciones como LG, Mercedes-Benz, AMD, Panasonic y Harman confían en Qt para sus stacks de UI.

Versiones de PyQt

Riverbank Computing ofrece dos bindings principales:

• PyQt4 — soporta módulos Qt 4.x y Qt 5.x (no backward compatible)
• PyQt5 — bindings exclusivamente para Qt 5.x

Adicionalmente, PyQt3D provee bindings Python para el framework Qt3D, útil para rendering 3D en tiempo real y simulación.

Instalando PyQt5

Dos métodos comunes de instalación se describen abajo. Recomendamos usar paquetes wheel porque incluyen binarios C++ compilados y evitan procesos de build largos.

Método 1: Instalación vía Wheels (Recomendado)

1. Abre tu terminal o línea de comandos preferida.
2. Ejecuta pip install PyQt5 para descargar el wheel (≈ 50 MB).
3. Verifica que la instalación complete exitosamente.

Ejemplo en Windows:

pip install PyQt5

Una vez instalado, puedes importar PyQt5.QtWidgets y empezar a construir aplicaciones.

Método 2: Build desde Fuente

Compilar desde fuente es más complejo porque compila código C++. Solo es necesario si necesitas modificaciones custom o el wheel para tu plataforma no está disponible.

Fundamentos de Programación PyQt5

Abajo, ejemplo mínimo que abre ventana 300×300 titulada "Guru99". Cada línea está anotada para claridad.

import sys
from PyQt5.QtWidgets import QApplication, QWidget
if __name__ == "__main__":
    app = QApplication(sys.argv)
    w = QWidget()
    w.resize(300, 300)
    w.setWindowTitle("Guru99")
    w.show()
    sys.exit(app.exec_())

Explicación:

• QApplication — core event loop.
• QWidget — clase base para todos los componentes UI.
• resize() — establece dimensiones de ventana.
• setWindowTitle() — define texto de barra de título.
• show() — muestra el widget.
• app.exec_() — inicia event loop y bloquea hasta cerrar ventana.

Añadiendo Interactividad

El siguiente ejemplo añade label, botón y message box que aparece al hacer click. Demuestra signals y slots, el core del sistema de eventos de Qt.

import sys
from PyQt5.QtWidgets import QApplication, QWidget, QLabel, QPushButton, QMessageBox
def dialog():
    mbox = QMessageBox()
    mbox.setText("Tu lealtad ha sido registrada")
    mbox.setDetailedText("Ahora eres discípulo y súbdito del Guru omnisciente")
    mbox.setStandardButtons(QMessageBox.Ok | QMessageBox.Cancel)
    mbox.exec_()
if __name__ == "__main__":
    app = QApplication(sys.argv)
    w = QWidget()
    w.resize(300, 300)
    w.setWindowTitle("Guru99")
    label = QLabel("He aquí el Guru, Guru99", w)
    label.move(100, 130)
    btn = QPushButton("Visto", w)
    btn.move(110, 150)
    btn.clicked.connect(dialog)
    w.show()
    sys.exit(app.exec_())

Clickear el botón dispara dialog(), que crea un QMessageBox modal.

Componentes y Widgets Centrales

La arquitectura de PyQt5 está organizada en varios módulos. Entender esta jerarquía ayuda a importar solo lo necesario.

Visión General de Módulos

• Qt — agrega todos los sub-módulos; conveniente para scripts pequeños.
• QtCore — clases core no-GUI (signals, slots, timers).
• QtWidgets — widgets GUI estándar (botones, labels, etc.).
• QtGui — primitivas gráficas y painting avanzado.
• QtNetwork — sockets TCP/UDP, SSL, DNS.
• QtMultimedia — soporte audio/video.
• QtSql — integración base de datos.

Widgets Comunes

• QLineEdit — input de texto single-line.
• QRadioButton — botón radio seleccionable.
• QComboBox — selector dropdown.
• QCheckBox — checkbox toggle.
• QMenuBar — barra de menú horizontal.
• QToolBar — toolbar con botones.
• QTabWidget — interfaz con pestañas.
• QScrollBar — widget scroll bar.
• QSplitter — vista split redimensionable.
• QDockWidget — panel dock desmontable.

Gestión de Layouts

En lugar de posicionar widgets manualmente con move() y resize(), Qt ofrece layout managers que arreglan widgets automáticamente basado en tamaño de ventana.

Box Layouts (HBox & VBox)

QHBoxLayout arregla widgets horizontalmente; QVBoxLayout verticalmente.

import sys
from PyQt5.QtWidgets import QApplication, QWidget, QPushButton, QHBoxLayout, QVBoxLayout
app = QApplication([])
win = QWidget()
win.setWindowTitle("Mosqueteros")
btn1 = QPushButton("Athos")
btn2 = QPushButton("Porthos")
btn3 = QPushButton("Aramis")
hbox = QHBoxLayout(win)
hbox.addWidget(btn1)
hbox.addWidget(btn2)
hbox.addWidget(btn3)
win.show()
app.exec_()

Reemplaza QHBoxLayout con QVBoxLayout para apilar botones verticalmente.

Grid Layout

Organiza widgets en grid 2D. El método addWidget() acepta índices de fila y columna más argumentos opcionales de row-span y column-span.

import sys
from PyQt5.QtWidgets import QApplication, QWidget, QPushButton, QGridLayout
app = QApplication([])
win = QWidget()
layout = QGridLayout(win)
for i in range(3):
    for j in range(3):
        layout.addWidget(QPushButton(f"Botón {i},{j}"), i, j)
win.show()
app.exec_()

Temas y Estilos Personalizados

PyQt5 soporta temas nativos y stylesheets personalizados.

Temas Integrados

Establece estilo de aplicación con app.setStyle("Fusion") u otro estilo disponible.

app = QApplication([])
app.setStyle("Fusion")

Personalización de Paleta

Usa QPalette para modificar colores de widgets programáticamente.

from PyQt5.QtGui import QPalette
from PyQt5.QtCore import Qt
palette = QPalette()
palette.setColor(QPalette.ButtonText, Qt.black)
palette.setColor(QPalette.Window, Qt.black)
palette.setColor(QPalette.Button, Qt.gray)
app.setPalette(palette)

Qt Style Sheets (CSS-like)

Para styling avanzado, aplica stylesheets directamente a widgets o toda la aplicación.

btn.setStyleSheet("background-color: #4CAF50; color: white; padding: 5px;")

Puntos Clave

• PyQt5 es un potente binding Python para Qt, apto para apps desktop, embebidas y móviles multiplataforma.
• Instalación óptima vía wheels; builds desde fuente son opcionales.
• Módulos core: QtCore, QtGui, QtWidgets, QtNetwork, QtMultimedia, QtSql.
• Widgets incluyen botones, labels, campos de texto, radio buttons, checkboxes, menús, toolbars, tabs, splitters, docks.
• Interactividad se basa en mecanismo signals y slots de Qt.
• Layouts —Box y Grid— automatizan colocación de widgets, mejorando responsividad.
• Temático achievable con estilos integrados, paletas o Qt Style Sheets.
• Qt Designer y Qt Creator agilizan diseño UI y packaging de aplicaciones.