index.qmd

---
title: "Ambientes virtuales en Python: buenas prácticas para desarrollo de software de investigación"
subtitle: RS-Latam 2026
author:
  - name: Stephanie Orellana Bello
    url: https://github.com/sporella
    email: sporella.dev@gamil.com 
date: 2026-08-25
format:
  html:
    toc: true
    toc-depth: 4
    code-fold: false
    theme: minty
    number-sections: true
filters:
  - diagrams
lang: es  
---

# Un poco de Contexto

## Reproducibilidad

La reproducibilidad tiene diferentes capas, hoy aprenderemos solo de una parte.


![Ziemann, M., Poulain, P., & Bora, A. (2023). The five pillars of computational reproducibility: Bioinformatics and beyond. Briefings in Bioinformatics, 24(6), bbad375. https://doi.org/10.1093/bib/bbad375](img/pilares.png)


## ¿Por qué hablamos de ambientes?

En RSE, nuestro código no vive aislado.

Para ejecutar un proyecto necesitamos, entre otras cosas:

- una versión de Python;
- paquetes y dependencias;
- versiones compatibles;
- un ambiente donde instalar esas dependencias.

::: {.fragment}
> ¿Qué necesitas además de `main.py` para ejecutar un proyecto de otra persona?
:::

## Python


::::: {.process .chevron}

:::: item
Versión de Python

::: annotation
Pueden haber múltiples instaladas en el sistema
:::

::::

:::: item

Ambiente Virtual

::: annotation
Creamos un espacio aislado para instalar los paquetes que requiere nuestro proyecto
:::

::::

:::: item
Paquetes

::: annotation
Instalamos las librerías (y sus dependencias) necesarias para que nuestro código funcione
:::

::::

:::::

<br>

Esto garantiza una capa mínima de reproducibilidad, pero no resuelve:

- Mala organización del proyecto
- Falta de documentación
- Mal diseño de dependencias
- Diferentes sistemas operativos

### Versión de Python

Un proyecto puede requerir una versión específica de Python.

Por ejemplo:

```text
Python 3.11
Python 3.12
Python 3.13
```

Puedes consultar la versión que estás utilizando con:

```bash
python --version
```

### Paquetes

Python incluye una biblioteca estándar, pero muchos proyectos necesitan paquetes externos.

Por ejemplo:

```python
import pandas
import seaborn
```

Estos paquetes deben estar instalados en el ambiente donde ejecutamos nuestro proyecto.

### Ambiente virtual

Un ambiente virtual permite mantener aisladas las dependencias de un proyecto.

El caso de `pandas`. En enero de este año se lanzó la versión 3.0 de pandas que incluye una serie de cambios que hacen que ciertos códigos hechos con versiones anteriores ya no sean compatibles.

![](img/pandas_warning.png)

Acá es donde tener ambientes separados para nuestros proyectos resulta crucial:

```text
proyecto A
└── ambiente A
    └── pandas 2.x

proyecto B
└── ambiente B
    └── pandas 3.x
```

Así, cambiar las dependencias de un proyecto no debería romper otro.


## Muchas Herramientas

![Fuente: [Anna-Lena Popkes](https://alpopkes.com/posts/python/packaging_tools/#last-update)](img/venn_diagram_updated_08_2024.png)

# ¿Qué haremos hoy?

Un pequeño proyecto de Python que:

1. lee datos de temperatura desde un CSV disponible en GitHub
2. usa `pandas` para trabajar con los datos
3. usa `seaborn` para visualizar una serie temporal
4. usa `scipy` para calcular la tendencia

Esto es algo muy simple porque el foco del taller no es aprender a programar en Python. 

Acá aprenderemos a:

**Crear un ambiente virtual con `venv` e instalar los paquetes necesarios con `pip`**

  - [ ] Comprobar qué versión de python estamos usando
  - [ ] Crear el ambiente
  - [ ] Activar el ambiente
  - [ ] Instalar dependencias
  - [ ] Comprobar instalación
  - [ ] Generar archivo `requirements.txt`
  - [ ] Recrear el ambiente desde `requirements.txt`



**Hacer lo mismo (y más) con `uv`**

- [ ] Diferentes formas de iniciar un proyecto
- [ ] Diferentes archivos que genera y estructura de proyectos
- [ ] Crear un proyecto con una versión de python específica
- [ ] Instalar paquetes y crear un ambiente
- [ ] Corroborar sincronización con nuevas instalaciones
- [ ] Pasar de un proyecto tradicional a uno con uv

# Preparar el computador

## Python

Necesitamos una instalación funcional de Python.

Comprueba:

```bash
python --version
```

En algunos sistemas puede ser:

```bash
python3 --version
```

### Windows

Descarga Python desde la página oficial:

[https://www.python.org/downloads/windows/](https://www.python.org/downloads/windows/)

Durante la instalación, recuerda activar la opción para agregar Python al `PATH`.

![](img/python_path.png)

Si al ejecutar algún script en powershell recibes el mensaje:

```bash
la ejecución de scripts está deshabilitada en este sistema. Para obtener más información, consulta el tema about_Execution_Policies en https:/go.microsoft.com/fwlink/?LinkID=135170.
```

ejecuta en powershell

```bash
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

### macOS

Puedes instalar Python desde:

[https://www.python.org/downloads/macos/](https://www.python.org/downloads/macos/)

Si utilizas Homebrew:

```bash
brew install python
```

### Linux

Consulta las instrucciones oficiales para tu distribución:

[https://www.python.org/downloads/](https://www.python.org/downloads/)

En Ubuntu/Debian, por ejemplo:

```bash
sudo apt update
sudo apt install python3 python3-venv python3-pip
```

::: {.callout-note}
Si ya tienes Python instalado y `python --version` funciona, no necesitas instalarlo nuevamente.
:::


# Forma nativa: venv + pip

## Crear una carpeta para trabajar

Crearemos una carpeta de la manera usual según tu sistema operativo y la abriremos en el IDE que tengan instalado.

Yo estaré trabajando con Positron y VSCode


## Crear el ambiente

Ejecuta en la terminal:

```bash
python -m venv .venv
```

Esto crea una carpeta `.venv` con el ambiente virtual.

## Activar el ambiente

El ambiente debe activarse para ser usado, la manera de activarlo varía según el sistema operativo que utilizamos.

### macOS / Linux

En la terminal

```bash
source .venv/bin/activate
```

### Windows PowerShell

```powershell
.venv\Scripts\Activate.ps1
```

### Windows CMD

```cmd
.venv\Scripts\activate.bat
```

Cuando el ambiente está activo, normalmente verás `(.venv)` al comienzo de la línea de comandos.

## Comprobar el Python utilizado

En la terminal

```bash
python --version
```

## Crea el archivo de código de ejemplo

Crearemos un nuevo archivo llamado `main.py` con el siguiente contenido:

```python
import pandas as pd
import seaborn as sns
import matplotlib.pyplot as plt

# Leer datos desde GitHub
url = "https://raw.githubusercontent.com/datasets/global-temp/main/data/annual.csv"

df = pd.read_csv(url)

# Filtrar datos de GISTEMP
df = df[df["Source"] == "GISTEMP"]

# Graficar anomalía de temperatura global
sns.lineplot(data=df, x="Year", y="Mean")

plt.title("Anomalía de temperatura global")
plt.xlabel("Año")
plt.ylabel("Anomalía de temperatura (°C)")
plt.show()
```


## Instalar paquetes

Ahora instalaremos las dependencias del ejemplo:

```bash
pip install pandas seaborn
```

Puedes revisar qué quedó instalado:

```bash
pip list
```

Quiero incluir una línea de tendencia en mi gráfico, así que modifico el código:

```python
import pandas as pd
import seaborn as sns
import matplotlib.pyplot as plt
from scipy.stats import linregress

url = "https://raw.githubusercontent.com/datasets/global-temp/main/data/annual.csv"

df = pd.read_csv(url)
df = df[df["Source"] == "GISTEMP"]

# Calcular regresión lineal
result = linregress(df["Year"], df["Mean"])

# Línea de tendencia
df["Trend"] = result.intercept + result.slope * df["Year"]

# Graficar
sns.lineplot(data=df, x="Year", y="Mean", label="Temperatura")
sns.lineplot(data=df, x="Year", y="Trend", label="Tendencia")

# Ecuación
equation = f"y = {result.slope:.4f}x + {result.intercept:.2f}"

plt.text(
    0.05,
    0.95,
    equation,
    transform=plt.gca().transAxes,
    verticalalignment="top"
)

plt.title("Anomalía de temperatura global")
plt.xlabel("Año")
plt.ylabel("Anomalía de temperatura (°C)")
plt.tight_layout()
plt.show()
```

Y debo instalar el nuevo paquete

```bash
pip install scipy
```

## Guardar las dependencias

Una forma tradicional de registrar las dependencias es:

```bash
pip freeze > requirements.txt
```

Esto genera:

```text
requirements.txt
```

Puedes abrirlo y revisar las versiones instaladas.

## Ejecutar el ejemplo

Ejecuta:

```bash
python main.py
```

# Forma con: uv

`uv` es una herramienta moderna para gestionar proyectos, ambientes, versiones de Python y dependencias.

Documentación oficial:

[https://docs.astral.sh/uv/](https://docs.astral.sh/uv/)

Una captura de pantalla sobre lo que promete:

![](img/uv.png)

## Instalar uv
### macOS y Linux

La instalación oficial ofrece un instalador independiente:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

También puedes utilizar Homebrew en macOS:

```bash
brew install uv
```

### Windows

En PowerShell:

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

También puedes instalarlo mediante WinGet:

```powershell
winget install --id=astral-sh.uv -e
```

::: {.callout-note}
Después de instalar `uv`, abre una nueva terminal si el instalador te indica que debes actualizar el `PATH`.
:::

Comprueba la instalación:

```bash
uv --version
```

## Crear el proyecto con uv

### Proyecto por defecto

Primero exploraremos un proyecto de `uv` que se crea con las configuraciones por defecto. Es una buena forma de entender cómo estructurar nuestros proyectos de python más complejos.

Haremos una nueva carpeta para trabajar y la abriremos en nuestro IDE.

Puedes crear un proyecto nuevo desde la terminal con:

```bash
uv init
```

Esto crea la estructura básica del proyecto como tipo "aplicación empaquetada"

```
mi-proyecto/
├── .python-version   ← versión de Python
├── .venv/            ← ambiente virtual
├── README.md         ← documentación
├── pyproject.toml    ← configuración y dependencias
├── uv.lock           ← versiones concretas de las dependencias
└── src/              ← código fuente
    └── mi_proyecto/
        └── __init__.py
```

Este tipo de estructura inicial es muy útil para comenzar nuestros proyectos de manera ordenada y con los archivos mínimos para garantizar su reproducibilidad.

Acá dejo un recordatorio de qué significa cada cosa en el `pyproject.toml``

```toml
[project]

name = "proyecto-uv0"             # ¿Cómo se llama?
version = "0.1.0"                 # ¿Qué versión?
description = "..."               # ¿Qué hace?
readme = "README.md"              # ¿Dónde está la documentación?
authors = [...]                   # ¿Quién lo desarrolla?
requires-python = ">=3.13"       # ¿Qué Python necesita?
dependencies = [...]              # ¿Qué paquetes necesita?

[project.scripts]
proyecto-uv0 = "proyecto_uv0:main" # ¿Cómo lo ejecuto?

[build-system]
...                                # ¿Cómo se construye?
```

### Proyecto forma simple

Haremos una nueva carpeta y la abriremos en nuestro IDE. Ahora utilizaremos algunas opciones de `uv init` para adecuar la estructura a nuestro código simple

```bash
uv init --no-package --python 3.13
```

Acá le decimos que queremos una aplicación simple "no empaquetada" y que use la versión 3.13 de python


#### Agregar dependencias

En lugar de instalar los paquetes directamente con `pip` como en el ejemplo anterior con `uv` podemos declarar las dependencias del proyecto:

```bash
uv add pandas seaborn
```

`uv` crea o actualiza:

```text
pyproject.toml
uv.lock
.venv
```

Mirar el arbol de dependencias:

```bash
uv tree
```

#### Ejecutar el proyecto

Con `uv` puedes ejecutar el programa mediante:

```bash
uv run python main.py
```

Esto es todo, `uv` se encargua de utilizar el ambiente y las dependencias correspondientes.

# Pasar de un método a otro

| | `venv` + `pip` | `uv` |
|---|---|---|
| Ambiente virtual | `venv` | `uv venv` |
| Activar ambiente | `source .venv/bin/activate` (macOS/Linux) `.\.venv\Scripts\activate` (Windows) | No es necesario |
| Instalar paquetes | `pip install` | `uv add` |
| Declarar dependencias | `requirements.txt` o `pyproject.toml` | `pyproject.toml` |
| Versiones bloqueadas | `requirements.txt` | `uv.lock` |
| Gestionar Python | No, solo ejecutables instalados | Sí |
| Ejecutar proyecto | Activar `.venv` y `python main.py` | `uv run` |

## Si alguien que usa `uv` quiere reconstruir un ambiente hecho con `venv+pip`

```bash
uv venv
uv pip install -r requirements.txt
```

## Si alguien que no usa `uv` quiere colaborar en un proyecto `uv`

```bash
python -m venv .venv # usar la versión de python especificada en toml, si no no funciona
soruce .venv/bin/activate # en mac/Linux, en windows .\.venv\Scripts\activate
pip install . # lee desde toml
```

## Si alguien usa `uv` quiere colaborar

```bash
uv sync
```

# Ideas finales

1. La versión de Python y los paquetes son cosas diferentes
2. Un ambiente virtual aísla las dependencias de un proyecto
3. `venv` crea el ambiente y `pip` instala paquetes
4. `pyproject.toml` permite declarar requisitos del proyecto, no es algo propio de `uv` sino que es un estándar de Python
5. `uv` integra la gestión de Python, ambientes y dependencias
6. `uv.lock` ayuda a reproducir las versiones resueltas
7. Ninguna de estas herramientas, por sí sola, reproduce completamente el sistema operativo
8. Ninguna de estas herramientas, por sí sola, hace que nuestro proyecto sea 100% reproducible, esto es solo una capa

::: {.fragment}
> Si tienes dudas o comentarios: sporella.dev@gmail.com
:::