Flujo de trabajo: escribir código

En este capítulo veremos las distintas formas en que puedes escribir y ejecutar código. Esto puede resultar muy confuso si recién estás empezando a programar.

Existen distintas formas de escribir (y ejecutar) código que se adaptan a distintas necesidades. Por ejemplo, para crear un pipeline reproducible de tareas o escribir software de calidad de producción, podrías optar por un script——un archivo que es principalmente código. Pero para enviar instrucciones a un colega o explorar una narrativa, podrías elegir escribir tu código en un notebook, porque puede presentar texto y código juntos de forma más natural que un script.

Ya vimos algunas formas de escribir y ejecutar código en los capítulos anteriores. Aquí seremos un poco más sistemáticos para que, al final del capítulo, te sientas cómodo escribiendo código tanto en scripts como en notebooks. Para usuarios avanzados, también hay información sobre cómo escribir código con markdown, usando archivos markdown que contienen fragmentos de código ejecutable. De todos modos, los scripts y los notebooks son, con diferencia, las formas más populares de escribir código.

Empecemos con algunas definiciones.

Veamos ahora todas las formas en que puedes escribir código en un entorno de desarrollo integrado completo como Visual Studio Code. Cada una tiene ventajas y desventajas, y probablemente quieras usarlas en distintos momentos. La tabla siguiente muestra todas las formas en que puedes escribir y ejecutar código.

Si buscas un flujo de trabajo típico, este libro recomienda trabajar con scripts (archivos que terminan en .py) y la ventana interactiva de VS Code. Recuerda que, si trabajas con un archivo .py, siempre puedes abrir la ventana interactiva de Visual Studio Code haciendo clic derecho en algún lugar del script y seleccionando ‘Run in interactive window’.

Qué Cómo usarlo Requisitos previos Ventajas Desventajas
Script, p. ej. script.py ‘Run in interactive window’ en un entorno de desarrollo integrado (IDE) Instalación de Python + un IDE compatible con Python, p. ej. Visual Studio Code. Se puede ejecutar todo de una vez o paso a paso según se necesite. Hay herramientas muy potentes para ayudar a programar en scripts. Estándar de facto para código de calidad de producción. Otros scripts pueden importarlo. Compatible con el control de versiones. No es muy adecuado si quieres incluir mucho texto junto al código.
Jupyter Notebook, p. ej. notebook.ipynb Abre el archivo con Visual Studio Code. Usa Visual Studio Code y la extensión Jupyter de VS Code. El código y el texto pueden alternarse en el mismo documento. Los resultados enriquecidos del código pueden integrarse en el documento. Se puede exportar a PDF, HTML y más, controlando si se muestran las entradas/salidas del código, ya sea directamente o mediante Quarto. Se puede ejecutar todo de una vez o paso a paso según se necesite. Engorroso de usar con control de versiones. El código y el texto no pueden mezclarse en la misma ‘celda’. No es fácil importarlo en otros archivos de código.
Markdown con fragmentos de código ejecutable usando Quarto, p. ej. markdown_script.qmd Para generar resultados, escribe una mezcla de markdown y bloques de código y luego exporta con comandos como quarto render markdown_script.qmd --to html en la línea de comandos o usando la extensión de Visual Studio Code. Hay otros tipos de salida disponibles. Instalaciones de Python y Quarto, además de sus dependencias. Permite mezclar realmente texto y código. Se puede exportar a una gran variedad de formatos, como PDF y HTML, controlando si se muestran las entradas/salidas del código. Compatible con el control de versiones. Otros archivos de código no pueden importarlo.

Algunas de las opciones anteriores usan la línea de comandos, una forma de dar instrucciones en texto a tu computadora. Recuerda que puedes acceder a la línea de comandos (también llamada terminal) mediante la app Terminal en Mac, la app Símbolo del sistema (Command Prompt) en Windows, o ctrl + alt + t en Linux. Para abrir la línea de comandos dentro de Visual Studio Code, puedes usar el atajo de teclado ⌃ + ` (en Mac) o ctrl + ` (Windows/Linux), o hacer clic en “View > Terminal”.

Ahora veamos con más detalle cada una de estas formas de ejecutar código usando un ejemplo común: ¡Hello World!

Scripts

La mayor parte del código se escribe en scripts, y deberían ser tu opción por defecto.

Ya conocimos los scripts, pero hagamos un repaso. Crea un archivo nuevo en Visual Studio Code llamado hello_world.py. En el editor de Visual Studio Code, añade una sola línea al archivo:

print('Hello World!')

Guarda el archivo. Haz clic derecho y, para ejecutar el script, puedes usar ‘Run current file in interactive window’, ‘Run current file in terminal’ o ‘Run selection/line in interactive window’. Estos son dos métodos distintos de ejecutar el script: en el IDE (VS Code en este caso) o en la línea de comandos.

Un flujo de trabajo típico sería seleccionar algunas líneas dentro de un script y luego pulsar ‘Run selection/line in interactive window’ o usar el atajo de teclado shift + enter.

Como alternativa a lo último, puedes abrir tú mismo la línea de comandos y ejecutar

python hello_world.py

lo que ejecutará el script.

Jupyter Notebooks

Los Jupyter Notebooks sirven para experimentar, hacer pruebas y mantener juntos el texto y el código. Son los cuadernos de laboratorio del mundo de la programación. ¡Este libro está escrito en su mayor parte en Jupyter Notebooks! El nombre ‘Jupyter’ hace referencia a los tres lenguajes originales compatibles con Jupyter, que son Julia, Python y R, y a los cuadernos de Galileo en los que registró el descubrimiento de las lunas de Júpiter. Hoy los Jupyter notebooks admiten una enorme cantidad de lenguajes más allá de los tres originales, como Ruby, Haskell, Go, Scala, Octave, Java y más.

Para empezar con los Jupyter Notebooks, necesitarás tener una instalación de Python y ejecutar uv add jupyterlab en la línea de comandos.

Si te quedas atascado con este tutorial, hay un tutorial más detallado de VS Code y Jupyter disponible aquí.

Crea un archivo nuevo en Visual Studio Code y guárdalo como hello_world.ipynb. Cierra el archivo y vuelve a abrirlo. La interfaz de notebook debería cargarse automáticamente y verás opciones para crear celdas con signos de más etiquetados como ‘Code’ y ‘Markdown’. Una celda es un bloque independiente de código o de texto. Las celdas de texto contienen markdown, un lenguaje ligero para crear salidas de texto sobre el que aprenderás más en Markdown. Por ahora, crea una celda de markdown con lo siguiente:

# This is a title

## This is a subtitle

This notebook demonstrates printing 'hello world!' to screen.

Ahora, para la siguiente celda, elige código y escribe:

print('hello world!')

Para ejecutar el notebook, puedes elegir ejecutar todas las celdas (normalmente un botón de doble reproducción en la parte superior de la página del notebook) o solo una celda a la vez (un botón de reproducción junto a cada celda). ‘Ejecutar’ una celda de markdown mostrará el markdown renderizado; ejecutar una celda de código la ejecutará e insertará la salida debajo. Cuando ejecutes la celda de código, deberías ver aparecer el mensaje ‘hello world!’.

Los Jupyter Notebooks son versátiles y populares para la exploración inicial de ideas, especialmente en campos como la ciencia de datos. Todo este libro está escrito con una combinación de Jupyter Notebooks y markdown ejecutable (más sobre esto en un momento). Los Jupyter Notebooks también pueden ejecutarse fácilmente en la nube desde un navegador (mediante Binder o Google Colab) sin ninguna instalación previa. Aunque no tiene mucho código, la página que estás leyendo ahora puede cargarse en Google Colab como Jupyter Notebook haciendo clic en ‘Colab’ bajo el icono del cohete en la parte superior de la página.

Una característica muy útil de los Jupyter Notebooks es que puedes usarlos como archivos de entrada para Quarto en lugar de archivos .qmd, lo que abre muchas opciones y posibilidades de exportación (como ocultar parte del código de entrada). Puedes encontrar más información aquí (busca la guía sobre Jupyter Notebooks, es decir, archivos .ipynb) o adelantarte a los capítulos Markdown y Quarto.

Puedes probar un Jupyter Notebook en línea sin instalar nada en https://jupyter.org/try. Haz clic en Try Classic Notebook para ver un tutorial.

Consejos para usar Jupyter Notebooks

  • Control de versiones: si usas control de versiones, ten cuidado de no guardar las salidas de los Jupyter Notebooks cuando solo quieras guardar el código. La mayoría de los IDE compatibles con Jupyter Notebooks tienen una opción para borrar las salidas. También puedes automatizarlo como un pre-commit git hook (si no sabes qué es, no te preocupes). Otra opción es emparejar tu notebook con un script o un archivo markdown (lo veremos en la siguiente sección). Con o sin salidas, los Jupyter Notebooks se renderizan en github.

  • Comandos de terminal: se pueden ejecutar desde un Jupyter Notebook colocando ! delante del comando y ejecutando la celda. Por ejemplo, !ls lista el contenido del directorio en el que está el notebook, y !pwd muestra el directorio que contiene el notebook. También puedes usar !uv add de esta forma. Esto funciona igualmente en los notebooks de Google Colab, aunque en lugar de !uv add tendrás que ejecutar !pip install.

  • Comandos mágicos: las instrucciones que empiezan con % son comandos mágicos. %whos muestra información sobre las variables definidas. %run script.py ejecuta un script llamado script.py. %timeit mide cuánto tarda en ejecutarse la celda. Por último, puedes ver muchos más comandos mágicos con %quickref.

  • Las celdas de un notebook pueden ejecutarse en el orden que quieras. Pero si piensas compartir tu notebook o volver a usarlo tú mismo, es buena práctica comprobar que sus celdas hacen lo que quieres cuando se ejecutan en secuencia, de arriba abajo.

  • Hay muchísimas extensiones para Jupyter Notebooks; puedes encontrar una lista aquí. Destaca especialmente ipywidgets, que añade interactividad.

  • Obtén ayuda sobre un comando ejecutándolo con ? añadido al final.

Markdown con bloques de código ejecutable

Esta es, con diferencia, la forma menos común de programar, aunque ha ganado popularidad en los últimos años y es excelente si al final vas a exportar a otros formatos, como diapositivas, documentos ¡o incluso un sitio web!

Cuando tienes mucho más texto combinado con código, incluso los Jupyter Notebooks pueden resultar algo engorrosos y, históricamente, editar el texto en un notebook era un poco tedioso, sobre todo si querías mover mucho las celdas. Markdown ofrece una experiencia de escritura mucho más agradable. Pero markdown por sí solo no puede ejecutar código; imagina que quieres combinar reproducibilidad, texto, y código + salidas del código: existe una herramienta llamada Quarto que te permite hacerlo añadiendo bloques de código ejecutable a markdown.

Como se trata de un tema algo más avanzado, y tiene tanto que ver con la comunicación como con escribir código, volveremos a cómo hacerlo en Quarto.