Python (installation)

Les exercices à Hydro-Informatics utilisent des paquets Python scientifiques et géospatials. Installez ces paquets dans un environnement séparé pour contrôler les dépendances et éviter de modifier l’installation Python du système d’exploitation.

• Utilisez Miniforge et conda-forge pour l’environnement de cours, y compris flusstools, sur Windows, Linux et macOS.

• Utilisez pip + venv pour les exercices qui n’ont pas besoin de bibliothèques GDAL natives.

• Conserver les spécifications environnementales et enregistrer les versions utilisées pour chaque projet.

conda / mamba¶

Guide rapide (Miniforge)¶

1. Installez Miniforge3 pour votre système d’exploitation et votre architecture de processeur. Sous Windows, ouvrez Miniforge Prompt. Sous Linux/macOS, autoriser l’initialisation du shell pendant l’installation et rouvrir le terminal.

2. Téléchargez les flusstools environment.yml. Ouvrez un terminal dans le répertoire de téléchargement et créez l’environnement :

   conda env create -f environment.yml
   conda activate flussenv

Utilisez Python 3.11–3.13 pour cette spécification. Ses dépendances NumPy/SciPy nécessitent au moins Python 3.11, et exclut Python 3.14. Le fichier inclut JupyterLab et la pile géospatiale; il est partiellement épinglé, plutôt qu’un fichier de verrouillage exact.

3. Installez les flusstools à partir de PyPI après les dépendances conda:

   python -m pip install flusstools
   python -m pip check

4. Vérifiez les liaisons GDAL Python, le support NumPy raster et les flusstools :

   python -c "from osgeo import gdal, gdal_array; import flusstools as ft; print(gdal.VersionInfo('--version'))"

Une erreur d’importation indique une installation incomplète ou incompatible. Voir la documentation d’installation de flusstools.

Le modèle de projet Python fournit une structure de projet distincte. Son fichier environnement installe le code de projet local et doit être utilisé à partir du dépôt complet; téléchargement que YAML seul est insuffisant. Utilisez les spécifications de flusstools ci-dessus pour ce guide.

pip + venv sur Linux Mint/Ubuntu¶

Installer l’interprète de la distribution¶

sudo apt update
sudo apt install python3 python3-venv

Ces commandes installent la version Python de la distribution, qui doit satisfaire les dépendances de l’exercice.

Créer & activer un environnement¶

python3 -m venv ~/venvs/vflussenv
source ~/venvs/vflussenv/bin/activate
python -m pip install --upgrade pip

Un paquet par défaut venv isolats installés Python ; il ne fournit pas de bibliothèques natives comme GDAL.

Installer les exigences¶

Pour les exercices sans GDAL:

python -m pip install numpy pandas scipy matplotlib seaborn
python -m pip check

Si un exercice fournit un requirements.txt, vérifiez ses contraintes Python et package, puis installez-le avec python -m pip install -r requirements.txt.

Installer les flusstools¶

Utilisez l’environnement conda ci-dessus pour les flusstools. Une installation venv nécessite également GDAL ≥3.10, des en-têtes de développement et des liaisons Python correspondant à la version GDAL native. L’installation de libgdal-dev à partir d’une ancienne distribution ne répond pas nécessairement à ces exigences. Voir les instructions d’installation de GDAL Python avant de tenter de construire une source.

GDAL sur Windows et d’autres plateformes¶

Les publications officielles du GDAL sur PyPI fournissent actuellement des distributions sources. Les roues Rasterio et Fiona peuvent inclure leurs propres bibliothèques GDAL, mais elles ne fournissent pas les fixations osgeo importées séparément requises par les flusstools. Utilisez conda-forge pour l’environnement géospatial de ce cours sur les trois systèmes d’exploitation.

Installez des paquets supplémentaires avec pip¶

Exécutez pip par l’interprète actif:

python -m pip install seaborn

Cet exemple s’applique à un venv. Dans un environnement conda, ajoutez les dépendances disponibles à environment.yml et créez un environnement de remplacement comme décrit ci-dessous. Installez les paquets conda d’abord et pip-only les paquets, y compris flusstools, dernier. Voir les conseils de conda sur l’utilisation de pip.

Installation en vrac¶

Conservez les dépendances du projet dans une version révisée requirements.txt (venv) ou environment.yml (conda). Préserver les contraintes testées lors de l’enregistrement d’une analyse; remplacer chaque version exacte par >= n’établit pas la compatibilité.

Installer le noyau Jupyter¶

Inscrivez l’interprète utilisé pour les exercices :

conda activate flussenv
python -m ipykernel install --user --name fluss_kernel --display-name "Python (flussenv)"

source ~/venvs/vflussenv/bin/activate
python -m pip install jupyterlab ipykernel
python -m ipykernel install --user --name vfluss_kernel --display-name "Python (vflussenv)"

Dans JupyterLab, sélectionnez le nom d’affichage correspondant sous Kernel > Changer le noyau. Dans un cahier, import sys; print(sys.executable) identifie l’interprète du noyau.

Environnements de mise à jour¶

Mettre à jour l’environnement virtuel (venv)¶

Enregistrez les versions installées, vérifiez les mises à jour disponibles et mettez à jour uniquement les paquets requis pour le projet :

source ~/venvs/vflussenv/bin/activate
python -m pip freeze > requirements-before.txt
python -m pip list --outdated
python -m pip install --upgrade jupyterlab
python -m pip check

Exécutez les cahiers d’exercices avant d’enregistrer une spécification révisée. Un fichier gele les distributions de Python ; il ne capture pas les bibliothèques natives ni ne garantit le retour. Recréer un environnement à partir de la spécification précédente testée si nécessaire.

Mettre à jour l’environnement conda¶

Enregistrer l’environnement actuel avant d’examiner les changements à environment.yml:

conda env export -n flussenv > environment-before.yml
conda list -n flussenv --explicit > conda-explicit-before.txt

Le YAML enregistre les paquets conda et pip. Les spécifications explicites de conda identifient les constructions spécifiques à la plate-forme et excluent les paquets pip-only; aucun fichier ne garantit à lui seul une reproductibilité complète.

Créer un remplacement sous un nouveau nom, en préservant flussenv pour comparaison :

conda env create -n flussenv-next -f environment.yml
conda activate flussenv-next
python -m pip install flusstools
python -m pip check
python -c "from osgeo import gdal, gdal_array; import flusstools as ft"
python -m ipykernel install --user --name fluss_kernel_next --display-name "Python (flussenv-next)"

Testez les cahiers avec Python (flussenv-next) avant d’adopter le remplacement. Ne pas exécuter les mises à jour couverture pip sur les paquets gérés par conda : la liste de paquets dépassés de pip inclut également les distributions installées par conda.

Jupyter book 2 : auteur de livres et migration¶

Utilisez un environnement de création séparé:

conda create -n bookenv -c conda-forge python=3.13 pip nodejs=24
conda activate bookenv
python -m pip install "jupyter-book>=2,<3"
jupyter book --version

Jupyter Book 2 utilise le moteur de document MyST. Pour migrer un livre de version 1, travaillez sur une copie contrôlée par version. À partir du répertoire contenant _config.yml et _toc.yml, lancez :

jupyter book

Acceptez la rapidité de migration. La commande crée myst.yml et sauvegarde les fichiers de configuration originaux. Les extensions Sphinx personnalisées nécessitent des remplacements MyST ; conservez un environnement version 1 jusqu’à ce que les fonctionnalités requises soient disponibles. Consultez les avertissements de migration et les URLs de pages modifiées, y compris les redirections pour les pages publiées.

Construire et prévisualiser le livre migré :

jupyter book build --html --strict
jupyter book start

Le site statique est écrit à _build/html. Ouvrez l’URL de prévisualisation imprimée dans le terminal. Vérifiez les onglets, les avertissements et les renvois avant la publication. Voir le guide de migration.

Utilisation de l’environnement dans les IDE¶

JupyterLab¶

Activer flussenv ou vflussenv, puis lancer:

jupyter lab

Ouvrez l’URL imprimée dans le terminal et sélectionnez le noyau de cours enregistré.

PyCharm¶

Dans Paramètres > Python > Interprète > Ajouter Interprète > Ajouter Interprète local, sélectionnez l’environnement conda ou virtuel existant. Obtenez son chemin exécutable à partir d’un terminal activé:

python -c "import sys; print(sys.executable)"

Pour Linux venv ci-dessus, le chemin est ~/venvs/vflussenv/bin/python. Utilisez le chemin imprimé sur Windows plutôt que de supposer un répertoire d’installation Miniforge. Voir Configuration de l’interprète PyCharm.

Suppression des environnements¶

Avant de supprimer un environnement, supprimer son noyau Jupyter enregistré avec jupyter kernelspec uninstall fluss_kernel (ou vfluss_kernel) alors que Jupyter est toujours disponible. Désactiver l’environnement avant de l’enlever. Préserver les carnets et les fichiers de projet en dehors du répertoire environnement.

• Venv (Linux): lancez deactivate, puis rm -rf ~/venvs/vflussenv.

• Conda: lancez conda deactivate, puis conda env remove -n flussenv.

Résumé de l’installation¶

• Utiliser Miniforge et la spécification d’environnement de flusstools pour les exercices géospatials.

• Utilisez venv pour des exercices Python ordinaires sans exigences GDAL natives.

• Installez les dépendances conda avant les paquets pip-only et vérifiez les importations.

• Conserver les spécifications testées et valider les mises à jour avec les cahiers de cours.

• Gardez Jupyter Livre auteur séparé de l’environnement de cours de calcul.