Aller au contenu

Configurer VS Code pour l'auto-import des classes Forge

Ce guide configure VS Code et Pylance pour qu'ils résolvent et proposent automatiquement (Ctrl + ., puis « Ajouter l'import »)
les classes du framework Forge (paquet core, fourni par forge-mvc) dans un projet Forge nu.

Pourquoi cette configuration est nécessaire

Le code du framework (core.mvc.controller.BaseController, etc.) n'est pas présent dans le dépôt du projet.
Il est installé dans le .venv via le paquet forge-mvc.
Sans réglage, Pylance ne sait ni où le chercher, ni à quelle profondeur l'indexer, donc l'auto-import ne fonctionne pas.

Cette aide est optionnelle : Forge ne dépend pas de VS Code.
Elle améliore seulement le confort d'écriture des contrôleurs et des classes applicatives.

Vue d'ensemble

Pour la liste complète des extensions et de la configuration VS Code du projet, voir Environnement VS Code de Forge.

Prérequis

  • Le projet dispose d'un environnement virtuel avec forge-mvc installé :
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt   # contient forge-mvc==…
  • Les extensions VS Code Python (ms-python.python) et Pylance (ms-python.vscode-pylance) sont installées.

Vérifier d'abord que l'import fonctionne côté interpréteur.
Si cette commande échoue, le problème vient de l'installation, pas de VS Code :

.venv/bin/python -c "from core.mvc.controller import BaseController; print('OK')"

Configuration

Créer (ou compléter) le fichier .vscode/settings.json à la racine du projet :

{
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
  "python.analysis.autoImportCompletions": true,
  "python.analysis.indexing": true,
  "python.analysis.packageIndexDepths": [
    { "name": "core", "depth": 4, "includeAllSymbols": true }
  ]
}

Rôle de chaque clé

Clé Rôle
python.defaultInterpreterPath Pointe Pylance vers le Python du .venv, là où core est installé.
python.analysis.autoImportCompletions Active les suggestions d'import dans l'autocomplétion.
python.analysis.indexing Active l'indexation des paquets installés, nécessaire à l'auto-import.
python.analysis.packageIndexDepths Au pluriel. Force Pylance à indexer le paquet core en profondeur.

Pourquoi depth: 4 ?

Par défaut, Pylance n'indexe les paquets installés qu'au niveau 1 (le __init__.py racine).
Or les classes Forge sont imbriquées plus profondément, par exemple :

core / mvc / controller / base_controller.py   →  niveau 3

depth: 4 couvre largement l'arborescence de core.
includeAllSymbols: true indexe tous les symboles, pas seulement ceux listés dans __all__.

Piège fréquent : le pluriel

Le paramètre s'écrit packageIndexDepths (avec un s).
Écrit au singulier (packageIndexDepth), il est silencieusement ignoré et l'auto-import ne fonctionne pas.

Activation (étapes obligatoires)

Les réglages ne sont pris en compte qu'après ces deux actions :

  1. Sélectionner l'interpréteur : Ctrl + Shift + P, puis Python: Select Interpreter, et choisir ./.venv/bin/python.
    La barre d'état (en bas) doit afficher .venv (3.x.x).

  2. Recharger la fenêtre (indispensable après toute modification de settings.json) : Ctrl + Shift + P, puis Developer: Reload Window.

Patienter une quinzaine de secondes : Pylance ré-indexe core en arrière-plan.

Vérification

  1. Dans un contrôleur, écrire une classe qui hérite d'une classe Forge sans l'importer :
class WelcomeController(BaseController):

    @staticmethod
    def index(request):
        return Response.text("Bonjour Forge")
  1. BaseController est souligné (signalé comme non défini).
  2. Placer le curseur sur BaseController, puis Ctrl + . : la correction rapide « Ajouter l'import "BaseController" depuis core.mvc.controller »
    doit apparaître.
    La sélectionner insère l'import en haut du fichier.

Dépannage

L'auto-import n'apparaît toujours pas ?
Vérifier dans l'ordre :

  1. L'interpréteur : la barre d'état doit afficher .venv, pas un « Python 3.x »
    système.
    Sinon, relancer Python: Select Interpreter, puis recharger la fenêtre.

  2. Pylance a-t-il relu la configuration ?
    Ouvrir Affichage → Sortie, canal Pylance (ou « Serveur de langage Python »).
    Après un rechargement, une ligne Indexing … indexed N files doit apparaître.
    Si N reste très bas (proche du seul nombre de fichiers du projet), l'indexation de core n'a pas eu lieu : recharger à nouveau la fenêtre.

  3. Configuration réellement appliquée ?
    Le settings.json doit avoir été enregistré avant le dernier rechargement.
    Toute édition postérieure exige un nouveau Developer: Reload Window.

  4. Repli si l'interpréteur reste mal détecté : ajouter explicitement le chemin des paquets (adapter la version de Python) :

"python.analysis.extraPaths": ["${workspaceFolder}/.venv/lib/python3.12/site-packages"]
  1. Vérifier que core est bien installé dans le .venv (voir la commande des prérequis).

Suivi de version

.vscode/settings.json peut être versionné : il documente la configuration attendue et profite à toute l'équipe.
En revanche, .venv/ doit rester dans le .gitignore.