Configurer le PYTHONPATH dans VS Code

Par Dad 3.0, 20/11/2023

Niveau : Débutant

Pour le développement Python, j’ai une préférence pour PyCharm. Mais le poids de cet IDE fait que j’utilise aussi, en second, Visual Studio Code (VS Code). Et il y a un truc galère pour l’exécution d’un script avec VS Code, c’est qu’il exécute Python dans le répertoire du script et non à la racine du projet.

Conséquence : quand j’ai une dépendance dans une arborescence de mon projet, il ne la trouve pas et l’exécution plante.

Pourquoi et quelle est la solution ? C’est ce que je vais détailler dans ce billet.

Ce dont vous aurez besoin…

Pour mettre en pratique, vous devez avoir VS Code installé avec le plug-in Python et un projet avec au moins un script dans un package.

Vous pouvez relire mon article sur le vocabulaire des ressources Python (qu'est ce qu'un script, un module, un package…).

Ce que vous apprendrez dans cet article…

Vous apprendrez à :

configurer le PYTHONPATH pour VS Code
ce qui permettra à un script de pouvoir être exécuté de l'interface VS Code où qu'il soit dans l'arborescence.

Avant de commencer, un rappel s'impose.

Rappel : Python et les chemins vers les ressources

Lorsqu’un programme Python prends de l’ampleur, vous devez organiser votre code pour vous y retrouver. Vous groupez alors des fonctions dans des modules eux-même dans des packages. Vous avez respecté les recommandations de structure de projet Python et votre script est dans votre package racine.

Et lorsque vous exécutez votre script, ça plante car le package de votre import n’est pas trouvé.

En effet, lorsque vous exécutez Python, celui-ci référence un certain nombre de répertoires comme racines de dépendances. Il s’agit des chemins de l’installation système, des chemins de la variable d’environnement PYTHONPATH et du répertoire d’exécution de Python. Le piège, c’est que lorsque vous exécutez la commande suivante :

python package/script.py

Vous exécutez en fait Python dans le répertoire package et non à la racine du projet.

C’est la raison pour laquelle il faut exécuter un script Python à partir de la racine de votre projet avec la commande :

python -m package.script

Cependant, quand vous exécutez un script avec VS Code (avec le bouton), VS Code exécute la première commande, donc dans le répertoire du script. Python ne connait donc pas la racine du projet, donc le chemin vers vos autres ressources.

Pour utiliser le bouton d’exécution et utiliser correctement les imports, le plus simple est d’ajouter la source de votre projet au PYTHONPATH. C’est ce que fait de manière automatique PyCharm et je vais vous indiquer ici comment faire pour que VS Code le référence.

Ajouter PYTHONPATH pour VS Code

Je vais vous présenter ici la méthode, selon moi, la plus adaptée qui consiste faire une configuration pour le projet.

Commencez par créer un fichier .env à la racine de votre projet. Un fichier .env est destiné à définir les variables d’environnement (comme PYTHONPATH) à utiliser lors de l'exécution de votre programme.

Déclarez dans ce fichier la variable d’environnement PYTHONPATH qui va pointer sur la racine de votre projet. Vous devez indiquer un chemin absolu. Par exemple, pour Mac ou Linux :

PYTHONPATH=/Users/username/projects/my_project

Ou pour Windows

PYTHONPATH=C:\\projects\my_project

Si vous avez besoin d’autres chemins dans le PYTHONPATH, parce que votre projet utilise d’autres projets par exemple, vous pouvez évidemment le compléter.

Vous devez maintenant paramétrer VS Code pour qu'il prenne en compte ce fichier. Pour cela, nous allons éditer le fichier settings.json de l’environnement de travail. Celui-ci est situé dans le répertoire .vscode à la racine du projet. Si il a été créé… Donc le plus simple est d’utiliser la palette de commande (ctrl+shift+p ou command+p) et saisir >settings.json afin de filtrer les résultats. Choisissez alors d’ouvrir les paramètres de l’espace de travail.

Accéder aux settings dans la palette VS Code

VS Code créera ce fichier si il n'existait pas et l’ouvrira en édition. Ajoutez alors la ligne suivante et votre fichier devra ressembler à cet extrait si il vient d'être créé.

{
    "python.envFile": "${workspaceFolder}/.env",
}

Si le fichier existait déjà, ajoutez cette ligne, par exemple, au début, en vous assurant qu’elle finisse bien par une virgule. Ce fichier au format JSON est une collection de couples clef/valeur.

Et voilà. Sauvegardez ce fichier et à partir de maintenant, vous devez trouver toutes les ressources de votre projet.

Attention, si vous utilisez le terminal, pensez à fermer celui ouvert avant la modification car il ne charge la configuration qu'au lancement.

Partage des configurations

Se pose une dernière question : ces deux fichiers doivent-ils être partagés dans les référentiels de code (Git ou autre).

Par principe, un fichier .env reste local car il s’agit de configurations spécifiques à votre poste. Si j’utilise un fichier .env, j’ai un .env-demo partagé afin que ceux qui récupèrent mon projet aient un modèle à adapter.

Le répertoire .vscode est également un répertoire que j’estime spécifique à un utilisateur. Je pars du principe qu’il concerne l’IDE (l’outil) et non le projet. Donc je ne partage pas les répertoires de configuration des outils.

En résumé, je ne partage pas ces deux fichiers. Néanmoins, il est indispensable de les documenter.