Gérer un monorepo Python avec UV Workspaces

Résumé de la gestion d’un monorepo Python avec UV Workspaces

Cette vidéo présente une manière propre de résoudre les problèmes qui surviennent lorsqu’on gère plusieurs applications Python dans un seul dépôt Git (monorepo) à l’aide de la fonctionnalité UV Workspaces.

1. Résumé de la vidéo

Problèmes

Lorsqu’on développe en même temps un outil CLI et une application FastAPI dans un même dépôt, les problèmes suivants apparaissent.

• Duplication de code : il faut copier-coller les fonctionnalités utilisées en commun par la CLI et l’API (par exemple une fonction de scraping de titres).
• Gestion d’environnement complexe : chaque application nécessite son propre environnement virtuel, ce qui peut provoquer des conflits de versions de dépendances ou gaspiller de l’espace disque.

Solution : UV Workspaces

UV Workspaces propose deux fonctionnalités clés pour résoudre ces problèmes.

1. Dépendances partagées et environnement virtuel unique

   • Il est possible de définir les dépendances communes dans le fichier pyproject.toml situé à la racine du projet.
   • En exécutant la commande uv sync, UV lit ce fichier de configuration et crée à la racine du dépôt un environnement virtuel unique (.venv) partagé par l’ensemble du dépôt.
   • Tous les sous-projets (CLI, API, etc.) partagent ainsi le même environnement et les mêmes dépendances, ce qui évite les conflits de versions et simplifie la gestion.

2. Partage de code via des packages internes

   • Le code commun dupliqué (par exemple la fonction fetch_headlines) peut être séparé dans un « package interne » distinct, comme core.
   • La configuration du workspace permet de faire reconnaître ce package core comme une source locale plutôt que comme un package venant de PyPI.
   • Les applications CLI et API peuvent alors réutiliser ce code commun en l’important, par exemple avec from core.news import fetch_headlines.

2. Comment utiliser UV Workspaces

Étape 1 : configurer le workspace

Créez un fichier pyproject.toml à la racine du projet, puis définissez la section [tool.uv.workspace] pour indiquer où se trouvent les sous-projets.

[tool.uv.workspace]  
# Reconnaît tous les sous-dossiers du dossier "packages" comme membres du workspace  
members = ["packages/*"]  

Étape 2 : gérer les dépendances

• Dépendances partagées : ajoutez au pyproject.toml racine les dépendances utilisées en commun par tous les projets (par exemple python-dotenv).
• Dépendances spécifiques : ajoutez dans le pyproject.toml de l’application concernée (par exemple packages/api/pyproject.toml) les dépendances utilisées uniquement par une application donnée (par exemple fastapi, uvicorn).
• En exécutant uv sync à la racine, UV analyse tous les pyproject.toml et installe dans l’environnement virtuel racine toutes les dépendances nécessaires.

Étape 3 : partager le code avec un package interne

1. Créez un nouveau package (dossier) destiné à contenir le code partagé, comme packages/core.
2. Ajoutez ce package dans le pyproject.toml racine comme une dépendance classique.
3. Ajoutez une section [tool.uv.sources] dans le pyproject.toml racine afin d’indiquer que le package core doit être recherché dans le workspace local plutôt que sur PyPI.

<!-- end list -->

[project]  
# 1. Ajouter le package interne comme dépendance  
dependencies = [  
    "core",  
    "python-dotenv"  
]  
  
# 2. Indiquer que 'core' est un package local du workspace  
[tool.uv.sources]  
core = { workspace = true }  

4. Exécutez à nouveau uv sync pour installer le package core comme source locale.
5. Vous pouvez ensuite importer le code commun depuis packages/api ou packages/cli avec une instruction du type from core.news import ....

Étape 4 : exécuter les projets

Pour lancer un projet spécifique, utilisez uv run --from <nom_du_package>.

# Lancer le serveur API  
uv run --from packages/api uvicorn main:app --reload  
  
# Lancer l’outil CLI  
uv run --from packages/cli python main.py  

3. Pour qui est-ce recommandé ?

• Pour gérer plusieurs petits scripts d’automatisation, webhooks, API, CLI, etc. dans un même dépôt.
• C’est particulièrement utile lorsque ces applications partagent une logique ou des dépendances communes.
• En revanche, ce n’est pas forcément adapté à un script unique, à un package destiné à être publié indépendamment sur PyPI, ou à des applications totalement sans lien entre elles.

---

Lien vers la vidéo originale : https://www.youtube.com/watch?v=N_ypJwV8Q8I

[pcj9024]

Cela ressemble beaucoup à pnpm.