PyScript permite ejecutar Python directamente dentro de una página web. En lugar de preparar un servidor para cada pequeño experimento, puedes cargar un entorno de Python en el navegador, escribir código dentro del HTML y conectar ese código con botones, formularios y otros elementos de la interfaz.
Esta posibilidad resulta atractiva para demostraciones, material educativo, pequeños prototipos y páginas interactivas. Sin embargo, PyScript no sustituye automáticamente a JavaScript ni convierte cualquier proyecto de escritorio en una aplicación web. Para utilizarlo bien, conviene entender cómo se carga, qué ocurre dentro del navegador y cuáles son sus limitaciones.
Qué es PyScript
PyScript es una plataforma que facilita el uso de Python en el navegador mediante tecnologías como WebAssembly y Pyodide. El navegador descarga los componentes necesarios, crea un entorno aislado y ejecuta el código sin instalar Python en el equipo del visitante.
La documentación oficial de PyScript presenta la sintaxis actual, ejemplos y opciones de configuración. Para comprender la base técnica, también es útil consultar la documentación oficial de Pyodide.
Cuándo conviene usarlo
- Ejercicios educativos que deben funcionar desde un enlace.
- Demostraciones de algoritmos y cálculos sin instalar dependencias locales.
- Visualizaciones pequeñas que utilizan paquetes compatibles.
- Prototipos que necesitan interactuar con elementos HTML.
- Documentación técnica con ejemplos ejecutables.
Para una aplicación web tradicional con autenticación, base de datos y reglas de negocio, normalmente seguirás necesitando un backend. La guía de FastAPI con Python muestra una alternativa cuando el código debe ejecutarse de forma segura en el servidor.
Estructura de una página básica
Crea un archivo index.html y añade los recursos indicados por la versión de PyScript que estés utilizando. La estructura conceptual es la siguiente:
<!doctype html>
<html lang="es">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Primer ejemplo con PyScript</title>
<link rel="stylesheet" href="URL_OFICIAL_DE_PYSCRIPT">
<script type="module" src="URL_OFICIAL_DE_PYSCRIPT"></script>
</head>
<body>
<h1>Python en el navegador</h1>
<script type="py">
print("Hola desde PyScript")
</script>
</body>
</html>Las direcciones de los recursos pueden cambiar entre versiones. Copia siempre la configuración desde la documentación oficial, no desde un tutorial antiguo.
Probar la página con un servidor local
Abrir el archivo directamente puede producir restricciones relacionadas con módulos y recursos. Una forma sencilla de probarlo es iniciar un servidor HTTP local:
python -m http.server 8000Después abre http://localhost:8000. Este servidor es apropiado para desarrollo local, no para publicar una aplicación en producción. Antes de continuar, también puedes revisar cómo organizar un proyecto con entornos virtuales de Python, aunque el código ejecutado por PyScript utilizará su propio entorno en el navegador.
Mostrar resultados en un elemento HTML
Una página interactiva necesita escribir resultados en el documento. El siguiente ejemplo calcula un total y lo muestra en un elemento:
<p id="resultado">Esperando cálculo...</p>
<script type="py">
from pyscript import document
precio = 24.90
cantidad = 3
total = precio * cantidad
document.querySelector("#resultado").innerText = (
f"Total: ${total:.2f}"
)
</script>Las f-strings permiten generar mensajes claros. La guía sobre formatear números con f-strings explica decimales, porcentajes, alineación y moneda.
Leer datos de un formulario
También puedes conectar una función de Python con un botón:
<label>
Cantidad:
<input id="cantidad" type="number" min="1" value="1">
</label>
<button id="calcular">Calcular</button>
<p id="salida"></p>
<script type="py">
from pyscript import document, when
@when("click", "#calcular")
def calcular(event):
campo = document.querySelector("#cantidad")
salida = document.querySelector("#salida")
try:
cantidad = int(campo.value)
if cantidad < 1:
raise ValueError
except ValueError:
salida.innerText = "Introduce una cantidad válida."
return
precio = 12.50
salida.innerText = f"Total: ${precio * cantidad:.2f}"
</script>Aunque el campo HTML tenga restricciones, el código debe validar los datos. El artículo sobre entrada y validación en Python explica la diferencia entre convertir un valor y comprobar sus reglas de negocio.
Cargar paquetes
PyScript puede utilizar parte de la biblioteca estándar y paquetes compatibles con el entorno del navegador. Dependiendo de la versión, las dependencias se declaran en un archivo o bloque de configuración. No todos los paquetes funcionan: algunos necesitan binarios, procesos del sistema, controladores o acceso al sistema operativo.
Para análisis de datos pequeños puedes probar NumPy, Pandas o bibliotecas compatibles. La guía de Pandas para principiantes ayuda a preparar tablas antes de llevar un ejemplo al navegador.
Separar el código Python
Cuando el ejemplo crece, evita colocar todo dentro del HTML. Crea un archivo como main.py y cárgalo según la sintaxis indicada por PyScript. Esta separación mejora el mantenimiento, permite utilizar un editor con resaltado y facilita las pruebas de funciones que no dependen del navegador.
def calcular_total(precio: float, cantidad: int) -> float:
if precio < 0:
raise ValueError("El precio no puede ser negativo")
if cantidad < 1:
raise ValueError("La cantidad debe ser positiva")
return precio * cantidadLas funciones independientes pueden probarse con Pytest antes de conectarlas con la interfaz.
Rendimiento y experiencia del usuario
La primera carga puede ser más pesada que una página convencional porque el navegador necesita descargar y preparar el entorno. Muestra un indicador de carga, reduce las dependencias y evita ejecutar cálculos innecesarios al abrir la página.
Para operaciones pequeñas, la experiencia puede ser adecuada. Para procesamiento intensivo, archivos enormes o tareas que deben continuar aunque el usuario cierre la pestaña, utiliza un backend o servicio especializado.
Seguridad y privacidad
El código enviado al navegador puede ser inspeccionado por el visitante. Nunca coloques contraseñas, claves privadas, tokens administrativos o reglas secretas dentro del HTML o de los archivos Python descargados. Las validaciones importantes deben repetirse en el servidor.
El aislamiento del navegador tampoco convierte cualquier dato en seguro. Revisa qué archivos carga el usuario, cuánto contenido se procesa y qué información se envía a servicios externos.
Limitaciones principales
- La carga inicial puede ser lenta.
- No todos los paquetes de Python son compatibles.
- El acceso al sistema operativo está restringido.
- El código del cliente no puede proteger secretos.
- La integración con el DOM requiere aprender conceptos web.
- Una actualización de PyScript puede cambiar la configuración recomendada.
Errores frecuentes
- Copiar etiquetas de una versión antigua.
- Abrir el archivo sin servidor local y confundir errores de origen.
- Cargar paquetes grandes sin necesidad.
- Suponer que Python reemplaza todos los conceptos de HTML, CSS y JavaScript.
- Guardar credenciales dentro del código enviado al navegador.
- Mezclar la lógica de cálculo con toda la manipulación visual.
Conclusión
PyScript facilita la creación de experiencias educativas y prototipos interactivos con Python en el navegador. Empieza con una página mínima, utiliza la configuración oficial de la versión actual, separa las funciones reutilizables y valida todas las entradas. Para aplicaciones críticas, mantén los secretos y las reglas importantes en un backend y utiliza PyScript como una capa interactiva, no como sustituto automático de toda la arquitectura web.
