Tutorial de PyQt5

Este tutorial de PyQt5 muestra como usar Python y Qt para crear una GUI en Windows, Mac o Linux. Esta cubrriá todos los pasos, incluyendo el instalador para tu app. Solo necesitarás Python 3.

Que es PyQt5?

PyQt es una librería que permite usar el framework de Qt que produce Interfaces de usuario gráficas, o GUIs. Qt está escrito en C++. Al usarlo desde Python, podrás escribir aplicaciones rápidamente sin sacrificar la velocidad de C++.

PyQt5 se refiere a la versión más reciente, 5 de Qt. Podrás encontrar la mención ocasional de (Py)Qt4 en la web, pero es vieja y no esta soportada ya.

Un competidor interesante a PyQt es Qt para Python. Su API es virtualmente idéntica pero a diferencia de PyQt, esta licenciada bajo la LGPL esta puede ser usada de forma gratuita en proyectos comerciales. Esta respaldada por la compañía de de Qt, y es el futuro. Usamos PyQt aquí por que es más madura. Desde que el API es tan similar, podrás fácilmente cambiar fácilmente entre tus apps a Qt para Python más adelante.

Instala PyQt

Esta es la mejor manera de manejar las dependencias en Python en una forma de ambientes virtuales. Un ambiente virtual es simplemente un directorio local que contiene todas las dependencias y librerías para un proyecto en especifico. A diferencia de una instalación a nivel sistema donde estas librerías podrían afectar otros proyectos igualmente.

Para crear un ambiente virtual en el directorio actual, ejecuta el siguiente comando:

python3 -m venv venv

Esto crea que el directorio venv/. Para activar el ambiente virtual en Windows, ejecuta:

call venv/scripts/activate.bat

En Mac y Linux, use:

source venv/bin/activate

Puedes usar el ambiente virtual para activarlo con el prefijo (venv) en tu linea de comando:

Creando y activado un ambiente virtual de Python

Para ahora instalar PyQt, ejecuta el siguiente comando:

pip install PyQt5==5.9.2

La razón de por que usando la versión 5.9.2 si esto no es un lanzamiento muy estable de (Py)Qt. Ademas esto es subjetivo – Felicitaciones! Has configurado PyQt5 exitosamente.

Crea un GUI

Llego el momento de escribir nuestra primer GUI en nuestra app! Con los ambientes virtuales son activas, inicia Python. Ejecutaremos que los comandos lo siguen:

Crearemos un Hola Mundo del app de PyQt en Ubuntu Linux

Primero, le diremos a Python para cargar PyQt por el comando de import:

from PyQt5.QtWidgets import QApplication, QLabel

Después, crearemos una QApplication con el comando:

app = QApplication([])

Esto es un requerimiento de Qt: Cada app de GUI será una instancia de QApplication. Muchas partes de Qt no funcionan hasta que hayas ejecutado sobre la linea. Así que necesitarás virtualmente en cada app de (Py)Qt que escribas.

Los brackets [] en la linea previa representa que los argumentos de la linea de comando pasaron a la aplicación. Ya que en nuestra app no se usa ningún parametros, dejamos los brackets vacios.

Ahora, para actualmente ver algo, creamos una etiqueta sencilla:

label = QLabel('Hola Mundo!')

Entonces, diremos que Qt para mostrar la etiqueta en la pantalla:

label.show()

Dependiendo en el sistema operativo, esto ya abre una ventana pequeña:

Captura de pantalla de la aplicación Hola Mundo de PyQt

el último paso es para dar control sobre lo que qt y pregunta al preguntar "ejecuta la aplicación hasta que el usuario lo cierre". Esto es hecho entre el comando:

app.exec_()

Si todo funciona como se espera, felicitaciones! Tu solos construyes tus primeras apps de GUI con Python y Qt.

Widgets

Todo lo que ves en un app de (Py)Qt es un widget: Botones, etiquetas, ventanas, diálogos, barras de progreso etc. Como los elementos en HTML, widgets son usualmente anidados. Por ejemplo, una ventana puede contener un botón, el cual a su vez contiene una etiqueta.

Las siguientes capturas muestra los widgets de Qt mas comúnes:

Captura de los widgets mas comunes de PyQt

Arriba hacia abajo, izquierda a derecha, son:

QLabel
QComboBox
QCheckBox
QRadioButton
QPushButton
QTableWidget
QLineEdit
QSlider

QProgressBar

Puedes descargar el código que por el app muestra en la imagen aquí, si estas interesado.

Layouts

En este ejemplo, tu GUI consistirá probablemente en múltiples widgets. En este caso, deberás decirle a Qt en como posicionarlo. Por ejemplo, puedes usar QVBoxLayout para apilar los widgets de forma vertical:

Ejemplo QVBoxLayout

El código para este ejemplo es:

from PyQt5.QtWidgets import QApplication, QWidget, QPushButton, QVBoxLayout

app = QApplication([])
window = QWidget()
layout = QVBoxLayout()
layout.addWidget(QPushButton('Top'))
layout.addWidget(QPushButton('Bottom'))
window.setLayout(layout)
window.show()
app.exec_()

Previamente, instanciamos a QApplication. Entonces, creamos una ventana. Usamos el típo mas básico de QWidget para esto por que solo actua como un contenedor que no queremos para tener un comportamiento especial. Después, creamos el layout y agregamos dos QPushButtons a este. Finalmente, le diremos a la ventana a usar este layout (y su contenido). Tal como nuestra aplicación previa, terminamos con una llamada con .show() y app.exec_().

Hay también muchas otros tipos de layouts (eg. QHBoxLayout para presentar elementos en una fila). Ver la documentación de Qt para mas información.

Estilos personalizados

Uno de las fortalezas de Qt es el de soportar los estilos personalizados. Hay muchos mecanismos para que personalices el estílo de tu aplicación. La sección delinea unas cuantas.

Estilos incluidos

La formad e cambiar la apariencia de tu aplicación esta hecho en el estilo global. Observa la captura de la ventana siguiente:

Screenshot of common Qt widgets using the Fusion style

Esto usa los estilos llamado Fusion. Si usas un estílo de Windows en su lugar, lo verás de la siguiente forma:

Screenshot of common Qt widgets using the Windows style

Para aplicar los estilos, usa app.setStyle(...):

from PyQt5.QtWidgets import *
app = QApplication([])
app.setStyle('Fusion')
...

los estilos disponibles dependen de la plataforma pero usualmente 'Fusion', 'Windows', 'WindowsVista' (Windows únicamente) y 'Macintosh' (solo Mac).

Colores personalizados

Si te gusta un estilo, pero quieres cambiarle los colores (eg. a un tema oscuro), entonces podrás usar la QPalette y app.setPalette(...). Por ejemplo:

from PyQt5.QtCore import Qt
from PyQt5.QtGui import QPalette
from PyQt5.QtWidgets import QApplication, QPushButton

app = QApplication([])
app.setStyle('Fusion')
palette = QPalette()
palette.setColor(QPalette.ButtonText, Qt.red)
app.setPalette(palette)
button = QPushButton('Hello World')

button.show()
app.exec_()

Esto cambia el color del texto del botón a rojo:

Captura de QPushButton con texto rojo en el estilo Fusion

Para un tema oscuro en el estílo Fusion, ver aquí.

Hojas de estilos

Adicionalmente a lo previo, puedes cambiar la apariencia de tu aplicación de hoja de estilos. Esta analogía de Qt a CSS, podremos usar este ejemplo para agregar algo de espacio:

from PyQt5.QtWidgets import QApplication, QPushButton

app = QApplication([])
app.setStyleSheet("QPushButton { margin: 10ex; }")
button = QPushButton('Hello World')

button.show()
app.exec_()

La ventana Qt con el botón rodeado con espacio extra.

Para mayor información sobre hojas de estilos, por favor ve la documentación de Qt.

Señales / conectores

Qt usa un mecanismo llamado señales para que reaccione a eventos tales como que el usuario de clic en un botón. Los siguientes ejemplos ilustran esto. Esto contiene un botón que, cuando pulsado, muestra una caja de mensaje:

from PyQt5.QtWidgets import *

app = QApplication([])
button = QPushButton('Click')

def on_button_clicked():
     alert = QMessageBox()
     alert.setText('You clicked the button!')
     alert.exec_()
     button.clicked.connect(on_button_clicked)
     button.show()
     app.exec_()

PyQt QMessageBox diciendo que un botón fue hecho clic

La linea interesante es: button.clicked is a signal, .connect(...) instalaremos el llamado slot. Esto es simplemente una función que obtiene el llamado cuando las señales ocurren. En el ejemplo previo, nuestro slot muestra una caja de mensajes.

Los términos del slot es importante cuando usamos Qt de C++, por que los slots deben ser declarados de forma especial en C++. In Python sin embargo, cualquier función puede ser un slot – vimos esto anteriormente. Por esta razón, la distinción entre los slots y funciones "normales" tienen poca relevancia para nosotros.

Las señales son ubicuas en Qt. Y claro que puedes definir tus propios. Este sin embargo esta mas aya que lo que este tutorial abarcará.

Compila tu aplicación

Ahora tienes el conocimiento básico para crear una GUI que responda a actividades del usuario. Digamos que has escrito una app. Este corre en tu equipo. Como se lo darás a otras personas, para que también puedan correrlo?

Podrías preguntar a los usuarios de tu app que instalen Python y PyQt como lo hicimos anteriormente, y darle tu código fuente. Pero eso es muy tedioso (y usualmente poco práctico). Lo que queremos es una versión auto-ejecutable de tu app. Eso es un ejecutable binario que pueda correr el sistema sin tener que instalar nada.

En el mundo de Python, el proceso de cambiar el código fuente a un ejecutable auto-contenido que llamaremos freezing. Aunque hay muchas librerías de dirección sus problemas – such as PyInstaller, py2exe, cx_Freeze, bbfreze, py2app, ... – freezing PyQt apps has traditionally been a surprisingly hard problem.

Usaremos una nueva librería llamada fbs para permitir crear una aplicación auto ejecutable por apps en PyQt. Para instalarlo, ingresa el comando:

pip install fbs PyInstaller==3.3.1

Entonces, ejecuta lo siguiente:

python3 -m fbs startproject

Esto te genera los siguientes valores:

Comandos para iniciar un nuevo proyecto con fbs

Cuando ejecutas en la linea de comando, deberá abrirse una ventana vacía:

Una ventana vacía con 'Hello World!' como título

Esto es un app de PyQt5 tal como las has visto previamente. Su código fuente esta en src/main/python/main.py en tu directorio actual. Pero aquí la parte interesante: ya que usamos fbs, esto se vuelve un ejecutable de forma independiente!

python3 -m fbs freeze

Esto pone un binario auto contenido en el directorio de target/MyApp/ de tu directorio. Puedes enviarlo a tus amigos (con el mismo sistema operativo que el tuyo) y serán capaz de correr tu App!

(Please note that fbs currently targets Python 3.5. If you have a different version and the above does not work, please install Python 3.5 and try again. On macOS, you can also install Python 3.5 with Homebrew.)
Bono: Crea un instalador

fbs también te permite crear un instalador para tu aplicación vía que el comando python3 -m fbs installer:

(si estás en Windows, necesitarás instalar NSIS y ponerlo en tu variable PATH.)

Para más información en como usar fbs para tu aplicación existente, por favor ver este artículo. O el tutorial de fbs.

Resumen

Si has llegado hasta aquí, entonces muchas felicidades. Esperemos que tengas una buena idea de como PyQt (y varias de sus partes) puedan ser usadas para escribir una aplicación de escritorio con Python. También ver como los fbs te permiten crear ejecutables independientes e instaladores.

Si tienes alguna pregunta o comentario a este tutorial, por favor comenta o escribeme un correo electrónico. Divertete escribiendo tus propias apps!