Curso de vibe coding con Python — Parte 4
Garantizar la reproducibilidad
Conserve su entorno con requirements.txt
Al terminar la Parte 3, su análisis ya funciona en su propio ordenador. El siguiente paso importante es dejar el entorno de forma que otras personas puedan reproducirlo, ya sean coautores, revisores o usted mismo dentro de un tiempo. En Python, lo habitual es guardar las bibliotecas y sus versiones en un único archivo de texto llamado requirements.txt. En esta parte verá cómo crearlo y cómo pueden usarlo otras personas para reproducir su entorno.
Por qué hace falta requirements.txt
Como se explicó en la Parte 1, el código de Python solo funciona si coinciden la versión de Python y las versiones de todas las bibliotecas. Un código escrito con pandas 2.2.0 puede fallar en el entorno de otra persona que solo tenga pandas 1.5.0.
requirements.txt es un archivo de texto que recoge cada biblioteca que ha usado junto con su versión, una por línea. Con este archivo, quien lo reciba puede instalar exactamente las mismas versiones de todas las bibliotecas con un solo comando.
pandas==2.2.0
openpyxl==3.1.2
matplotlib==3.8.2
numpy==1.26.3
seaborn==0.13.1
Crear requirements.txt
Con el entorno virtual activado (el que creó en la Parte 2 con el nombre .venv), ejecute en la terminal el comando siguiente.
Abra una terminal en VSCode desde «Terminal → New Terminal» en el menú superior. Después, ejecute el comando que corresponda a su sistema.
- En Windows (PowerShell), ejecute
.venv\Scripts\Activate.ps1 - En Windows (símbolo del sistema), ejecute
.venv\Scripts\activate.bat - En Mac o Linux, ejecute
source .venv/bin/activate
Cuando aparezca (.venv) al principio de la línea de comandos, el entorno virtual estará activado.
Con el entorno virtual activado, ejecute el comando siguiente.
pip freeze > requirements.txt
Si el comando termina sin errores, aparecerá un archivo llamado requirements.txt en la raíz de la carpeta del proyecto. Al abrirlo verá todas las bibliotecas instaladas en su entorno virtual, cada una con su versión.
my_first_analysis/
├── .venv/
├── data/
│ └── sample_data.xlsx
├── notebooks/
│ └── analysis.ipynb
├── results/
│ ├── scatter.png
│ └── statistics.csv
└── requirements.txt # ← recién creado
Cada vez que instale una biblioteca nueva a medida que avance el análisis, tendrá que actualizar requirements.txt. Acostúmbrese a ejecutar pip freeze > requirements.txt una vez más al final de todo.
Cómo reproduce su entorno otra persona
Para que un coautor o un revisor reproduzca su análisis, basta con la carpeta que usted le entregue y las instrucciones que lleva dentro. Veamos primero qué debe incluir.
Archivos y carpetas que se comparten
my_first_analysis/
├── data/ # Datos originales (solo los que se pueden compartir)
│ └── sample_data.xlsx
├── notebooks/
│ └── analysis.ipynb # Script de análisis
├── results/ # Figuras y tablas generadas (se incluyen como referencia)
├── requirements.txt # Creado en el paso 2
└── README.md # Instrucciones (se crean en el paso 4)
La carpeta .venv/ no se incluye. Quien reciba el proyecto la volverá a crear en su propio ordenador.
El entorno virtual (.venv) es el «cuarto de trabajo» propio del proyecto del que hablamos en la Parte 1. No hace falta enviar el cuarto en sí. Si entrega requirements.txt, que es la lista de herramientas que hay en ese cuarto, la otra persona puede montar el mismo cuarto en su ordenador. Por eso .venv se queda fuera del paquete.
Puede compartir la carpeta como prefiera. Puede comprimirla en un ZIP y enviarla por correo, compartirla en un servicio de almacenamiento en la nube o publicarla en GitHub o Zenodo, como se explica en la Parte 5.
Pasos para quien recibe la carpeta
Quien recibe la carpeta mira primero la versión de Python indicada en README.md y después comprueba si esa versión está instalada en su ordenador.
- Abra README.md y mire la versión de Python (por ejemplo, «Tested on Python 3.12»).
- Compruebe si esa versión está instalada. Ejecute
python --versionen una terminal (en Windows, si tiene varias versiones instaladas, pruebe conpy --list). Si no la tiene, descargue e instale la versión necesaria desde python.org/downloads. - Abra la carpeta en VSCode y ejecute en la terminal los comandos siguientes.
# Windows (using Python 3.12)
py -3.12 -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt
# Mac / Linux (using Python 3.12)
python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
La primera línea crea un entorno virtual con la versión indicada en README.md. Si se omite el número de versión, se usará el Python predeterminado del sistema, que puede comportarse de otra manera. La última línea, pip install -r requirements.txt, instala todas las bibliotecas en las versiones exactas de la lista.
Ahora la otra persona tiene exactamente el mismo entorno en el que usted ejecutó analysis.ipynb. Al ejecutar el código obtendrá las mismas figuras y estadísticas. Eso es la reproducibilidad.
Escribir las instrucciones en README.md
Le recomendamos encarecidamente incluir un archivo README.md en la carpeta. Es lo primero que leerá otra persona, así que conviene que tenga un contenido como el del ejemplo siguiente.
# Analysis Package for [Your Study Title]
## Setup
```
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\Activate.ps1
pip install -r requirements.txt
```
## Running the Analysis
Open `analysis.ipynb` in VSCode and run the cells from top to bottom.
Results will be saved to the `results/` folder.
## Python Version
Tested on Python 3.12.
README.md se puede crear y guardar como un archivo de texto normal en VSCode o en cualquier editor de texto.
Los símbolos como # y ``` del ejemplo anterior siguen unas reglas de formato llamadas Markdown. Basta con añadir unos pocos símbolos al texto normal para indicar títulos, bloques de código, listas y otros formatos de forma sencilla. Servicios como GitHub, Zenodo, Notion y Slack admiten Markdown, y GitHub muestra los archivos README.md ya formateados.
Encontrará una referencia completa en el artículo complementario «Guía rápida de Markdown». Para empezar, basta con conocer # (títulos) y ``` (bloques de código).
Lo que hay que tener en cuenta para una reproducibilidad completa
requirements.txt es muy útil, pero conviene tener en cuenta algunas cosas.
-
No se guarda la versión de Python.
requirements.txtsolo registra las bibliotecas, no la versión de Python. Escriba siempre en README.md algo como «Tested on Python 3.12» (con la versión que haya usado). - Bibliotecas que dependen del sistema operativo. Unas pocas bibliotecas solo funcionan en Windows o solo en Mac. Si el análisis tiene que funcionar en varios sistemas operativos, lo ideal es probarlo en cada uno.
-
Una lista muy larga.
pip freezeguarda todas las dependencias, así que el archivo puede quedar largo. Si le molesta, pida a un LLM que le ayude a dejar solo las bibliotecas que usted carga directamente conimport.
Aun así, para empezar no hay ningún problema en usar la salida de pip freeze tal cual. No busque la perfección. Lo importante es que exista un requirements.txt.
Excluir .venv con .gitignore (opcional)
Al compartir la carpeta en GitHub, lo habitual es excluir la carpeta .venv. Quien reciba el proyecto debe crearla de nuevo, y además ocupa bastante. Para excluirla, cree en la raíz de la carpeta del proyecto un archivo llamado .gitignore con el contenido siguiente.
.venv/
__pycache__/
*.pyc
.ipynb_checkpoints/
Con este archivo, esos archivos y carpetas se excluyen automáticamente al subir el proyecto a GitHub. La Parte 5 lo explica con más detalle.
Lo que ya sabe hacer
- Guardar su entorno con
pip freeze > requirements.txt - Permitir que otras personas lo reproduzcan con
pip install -r requirements.txt - Escribir las instrucciones de instalación en README.md
- Excluir los archivos innecesarios con .gitignore
En la Parte 5, la última, verá cómo publicar en Zenodo o GitHub la carpeta que ha preparado y cómo añadir el enlace al apéndice de su artículo para que su investigación sea totalmente reproducible.