Gestión de monorepos de Python con UV Workspaces

Resumen de la gestión de monorepos de Python con UV Workspaces

Este video presenta cómo resolver de forma ordenada los problemas que surgen al administrar varias aplicaciones de Python dentro de un solo repositorio Git (monorepo) usando la función UV Workspaces.

1. Resumen del video

Problemas

Cuando se desarrollan al mismo tiempo una herramienta CLI y una app con FastAPI dentro de un mismo repositorio, aparecen problemas como los siguientes.

• Duplicación de código: hay que copiar y pegar funciones compartidas entre la CLI y la API, como una función para rastrear titulares.
• Gestión compleja del entorno: como cada app necesita su propio entorno virtual, pueden surgir conflictos entre versiones de dependencias o desperdiciarse espacio en disco.

Solución: UV Workspaces

UV Workspaces ofrece dos funciones clave para resolver estos problemas.

1. Dependencias compartidas y un único entorno virtual

   • Se pueden definir dependencias comunes en el archivo pyproject.toml ubicado en la raíz del proyecto.
   • Al ejecutar el comando uv sync, UV lee este archivo de configuración y crea en la carpeta raíz un único entorno virtual compartido (.venv) para todo el repositorio.
   • Así, todos los subproyectos (CLI, API, etc.) comparten el mismo entorno y las mismas dependencias, lo que evita conflictos de versiones y facilita la administración.

2. Compartir código mediante paquetes internos

   • El código común duplicado, como la función fetch_headlines, puede separarse en un "paquete interno" independiente, como core.
   • Mediante la configuración del workspace, este paquete core se reconoce como una fuente local en lugar de PyPI.
   • Entonces, tanto la app CLI como la app API pueden reutilizar ese código común importándolo con from core.news import fetch_headlines.

2. Cómo usar UV Workspaces

Paso 1: configurar el workspace

Crea un archivo pyproject.toml en la carpeta raíz del proyecto y define la sección [tool.uv.workspace] para indicar dónde están los subproyectos.

[tool.uv.workspace]  
# Reconoce todas las subcarpetas dentro de la carpeta "packages" como miembros del workspace  
members = ["packages/*"]  

Paso 2: gestionar dependencias

• Dependencias compartidas: las dependencias que todos los proyectos usan en común, como python-dotenv, se agregan al pyproject.toml raíz.
• Dependencias individuales: las dependencias usadas solo por una app específica, como fastapi y uvicorn para api, se agregan al pyproject.toml de esa app (por ejemplo, packages/api/pyproject.toml).
• Si ejecutas uv sync desde la carpeta raíz, UV escanea todos los pyproject.toml e instala en el entorno virtual raíz todas las dependencias necesarias.

Paso 3: compartir código como paquete interno

1. Crea un nuevo paquete (carpeta) para el código compartido, como packages/core.
2. Agrega este paquete al pyproject.toml raíz como si fuera una dependencia normal.
3. Agrega la sección [tool.uv.sources] al pyproject.toml raíz para que el paquete core se busque dentro del workspace en lugar de en PyPI.

<!-- end list -->

[project]  
# 1. Agregar el paquete interno como dependencia  
dependencies = [  
    "core",  
    "python-dotenv"  
]  
  
# 2. Indicar que 'core' es un paquete local del workspace  
[tool.uv.sources]  
core = { workspace = true }  

4. Vuelve a ejecutar uv sync y el paquete core se instalará desde la fuente local.
5. Ahora, desde packages/api o packages/cli, puedes importar el código común con la sintaxis from core.news import ....

Paso 4: ejecutar proyectos

Para ejecutar un proyecto específico, usa uv run --from <nombre_del_paquete>.

# Ejecutar el servidor API  
uv run --from packages/api uvicorn main:app --reload  
  
# Ejecutar la herramienta CLI  
uv run --from packages/cli python main.py  

3. Cuándo conviene usarlo

• Cuando se administran varios scripts pequeños de automatización, webhooks, APIs, CLIs, etc., dentro de un solo repositorio.
• Es especialmente útil cuando estas aplicaciones comparten lógica o dependencias.
• En cambio, puede no ser adecuado para un solo script, para paquetes que se distribuirán de forma independiente en PyPI o para administrar apps totalmente ajenas entre sí.

---

Enlace al video original: https://www.youtube.com/watch?v=N_ypJwV8Q8I

[pcj9024]

Se parece bastante a pnpm.