Python (Installation)

Die Übungen unter Hydro-Informatics verwenden wissenschaftlich-geografische Python-Pakete. Installieren Sie diese Pakete in einer separaten Umgebung, um Abhängigkeiten zu steuern und die Python-Installation des Betriebssystems zu verändern.

Verwenden Sie Miniforge und conda-forge für die Kursumgebung, einschließlich flusstools, unter Windows, Linux und macOS.
Verwenden Sie pip +venv für Übungen, die keine nativen GDAL-Bibliotheken benötigen.
Behalten Sie Umgebungsspezifikationen und erfassen Sie die für jedes Projekt verwendeten Versionen.

`conda` / `mamba`¶

Kurzanleitung (Miniforge)¶

Installieren Sie Miniforge3 für Ihr Betriebssystem und Ihre Prozessorarchitektur. Öffnen Sie unter Windows Miniforge Prompt. Auf Linux/macOS erlauben Sie die Initialisierung der Shell während der Installation und öffnen Sie das Terminal wieder.
Download der flusstools environment.yml. Öffnen Sie ein Terminal im Download-Verzeichnis und erstellen Sie die Umgebung:
```
conda env create -f environment.yml
conda activate flussenv
```

Verwenden Sie Python 3.11–3.13 für diese Spezifikation. Seine NumPy/SciPy-Abhängigkeiten erfordern mindestens Python 3.11, und es schließt Python 3.14 aus. Die Datei enthält JupyterLab und den Geospatial-Stapel; es ist teilweise gepinnt, anstatt eine genaue Schlossdatei.

Installieren Sie flusstools von PyPI nach den conda Abhängigkeiten:
```
python -m pip install flusstools
python -m pip check
```

Überprüfen Sie die GDAL Python Bindungen, NumPy Raster Unterstützung und flusstools:

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

Ein Importfehler zeigt eine unvollständige oder unvereinbare Installation an. Siehe die Zuflusstools-Installationsdokumentation.

Missing pkg_resources in an existing environment

Für ModuleNotFoundError: No module named 'pkg_resources' von EarthPy gelten die gleichen Einschränkungen für die bestehende Umgebung:

conda install -n flussenv -c conda-forge "setuptools>=70,<82"

Aktivieren Sie flussenv und wiederholen Sie den Importcheck. EarthPy kann noch eine pkg_resources Abschreibungswarnung ausgeben. pip check prüft die angegebenen Anforderungen; sie erkennt diese nicht angemeldete Laufzeitabhängigkeit nicht. Halten Sie die Setuptools constraint in environment.yml für nachfolgende Installationen mit EarthPy 0.9.4.

Die Python Projektvorlage bietet eine separate Projektstruktur. Seine Umgebungsdatei installiert lokalen Projektcode und muss aus dem gesamten Projektarchiv verwendet werden; Download, dass YAML allein unzureichend ist. Verwenden Sie die oben angegebene flusstools Spezifikation für diese Anleitung.

`pip` + `venv` unter Linux Mint/Ubuntu¶

Installieren Sie den Dolmetscher der Distribution¶

sudo apt update
sudo apt install python3 python3-venv

Diese Befehle installieren die Python-Version der Distribution, die die Abhängigkeiten der Übung erfüllen muss.

Erstellen und Aktivieren einer Umgebung¶

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

Ein Standard venv isolates installierte Python-Pakete; es stellt keine nativen Bibliotheken wie GDAL zur Verfügung.

Einbauvorschriften¶

Für Übungen ohne GDAL:

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

Wenn eine Übung eine requirements.txt zur Verfügung stellt, überprüfen Sie ihre Python und Paketbeschränkungen, dann installieren Sie es mit python -m pip install -r requirements.txt.

Fließwerkzeuge installieren¶

Verwenden Sie die oben liegende conda-Umgebung für flusstools. Eine venv-Installation erfordert zusätzlich GDAL ≥3.10, Entwicklungs-Header und Python-Bindungen, die der nativen GDAL-Version entsprechen. Die Installation von libgdal-dev aus einer älteren Distribution erfüllt diese Anforderungen nicht unbedingt. Siehe die GDAL Python-Installationsanleitung vor dem Versuch eines Quellaufbaus.

GDAL auf Windows und anderen Plattformen¶

Offizielle GDAL-Releases auf PyPI bieten derzeit Source-Distributionen. Rasterio- und Fiona-Räder können eigene GDAL-Bibliotheken enthalten, aber sie liefern nicht die separat importierten osgeoBindungen, die von flusstools benötigt werden. Verwenden Sie conda-forge für die geospatiale Umgebung dieses Kurses auf allen drei Betriebssystemen.

Install extra packages with `pip`¶

Führen Sie pip durch den aktiven Dolmetscher:

python -m pip install seaborn

Dieses Beispiel gilt für eine venv. In einer conda-Umgebung fügen Sie die verfügbaren Abhängigkeiten an environment.yml und erstellen Sie eine Ersatzumgebung wie unten beschrieben. Installieren Sie conda Pakete zuerst und pip-only Pakete, einschließlich flusstools, last. Siehe conda’s Anleitung zur Nutzung von pip.

Großanlage¶

Behalten Sie die Projektabhängigkeiten in einem geprüften requirements.txt (venv) oder environment.yml (conda). Erwarten Sie getestete Einschränkungen bei der Erfassung einer Analyse; jede exakte Version durch >= ersetzt keine Kompatibilität.

Installieren Sie Jupyter Kernel¶

Registrieren Sie den Dolmetscher für die Übungen:

conda (Windows/Linux/macOS)

venv (Linux Mint/Ubuntu)

Die gelieferte Umgebung umfasst bereits JupyterLab und ipykernel.

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

Wählen Sie im JupyterLab den entsprechenden Anzeigenamen unter Kernel > Kernel ändern. In einem Notebook identifiziert import sys; print(sys.executable) den Dolmetscher des Kernels.

Aktualisierung von Umgebungen¶

Aktualisieren der virtuellen Umgebung (venv)¶

Erfassen Sie die installierten Versionen, überprüfen Sie die verfügbaren Updates und aktualisieren Sie nur die für das Projekt erforderlichen Pakete:

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

Führen Sie die Übungshefte aus, bevor Sie eine überarbeitete Spezifikation aufnehmen. Eine Freeze-Datei erfasst Python Distributionen; es erfasst keine nativen Bibliotheken oder garantiert Rollback. Rufen Sie bei Bedarf eine Umgebung aus der vorherigen geprüften Spezifikation an.

Konda-Umgebung aktualisieren¶

Erfassen Sie die aktuelle Umgebung, bevor Sie Änderungen an environment.yml:

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

Die YAML registriert Conda- und Pip-Pakete. Explicit conda Spezifikationen identifizieren plattformspezifische Builds und schließen pip-only Pakete aus; keine Datei allein garantiert vollständige Reproduzierbarkeit.

Erstellen Sie einen Ersatz unter einem neuen Namen, um flussenv zum Vergleich zu bewahren:

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)"

Testen Sie die Notebooks mit Python (flussenv-next) vor der Übernahme des Ersatzes. Führen Sie keine Decke-Pip-Upgrades über conda-managed Pakete aus: pip’s outdated-Paketliste enthält auch Distributionen, die von conda installiert sind.

Jupyter Buch 2: Buchautorisierung und Migration¶

Verwenden Sie eine separate Autorisierungsumgebung:

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 verwendet die MyST Document Engine. Um ein Version 1 Buch zu migrieren, arbeiten Sie an einer versiongesteuerten Kopie. Aus dem Verzeichnis mit _config.yml und _toc.yml laufen:

jupyter book

Akzeptieren Sie die Migrationsanforderung. Der Befehl erstellt myst.yml und unterstützt die ursprünglichen Konfigurationsdateien. Benutzerdefinierte Sphinx-Erweiterungen erfordern MyST-Ersatz; halten Sie eine Version 1 Umgebung, bis die erforderlichen Funktionen verfügbar sind. Überprüfen Sie Migrationswarnungen und geänderte Seiten-URLs, einschließlich Redirects für veröffentlichte Seiten.

Erstellen und Vorschau des migrierten Buches:

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

Die statische Website wird an _build/html geschrieben. Öffnen Sie die im Terminal gedruckte Vorschau-URL. Überprüfen Sie die Registerkarten, Anzeigen und Querverweise vor der Veröffentlichung. Siehe die Migration guide.

Nutzung der Umwelt in IDEs¶

JupyterLabor¶

Aktivieren Sie flussenv oder vflussenv

jupyter lab

Öffnen Sie die im Terminal gedruckte URL und wählen Sie den registrierten Kurskern.

PyCharm¶

In Einstellungen > Python > Interpreter > Interpreter > Interpreter > Lokale Interpreter hinzufügen*, wählen Sie die vorhandene conda oder virtuelle Umgebung. Erhalten Sie seinen ausführbaren Pfad von einem aktivierten Terminal:

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

Für den Linux venv ist der Pfad ~/venvs/vflussenv/bin/python. Verwenden Sie den gedruckten Pfad unter Windows anstatt ein Miniforge Installationsverzeichnis zu übernehmen. Siehe PyCharm Dolmetscherkonfiguration.

Umgebungen löschen¶

Bevor Sie eine Umgebung löschen, entfernen Sie den registrierten Jupyter Kernel mit jupyter kernelspec uninstall fluss_kernel (oder vfluss_kernel) und Jupyter ist noch verfügbar. Deaktivieren Sie die Umgebung, bevor Sie sie entfernen. Erhalten Sie Notizbücher und Projektdateien außerhalb des Umweltverzeichnisses.

**venv (Linux)*: Laufen Sie deactivate, dann rm -rf ~/venvs/vflussenv.
conda: laufen conda deactivate, dann conda env remove -n flussenv.

Zusammenfassung der Installation¶

Verwenden Sie Miniforge und die flusstools-Umgebungsspezifikation für geospatiale Übungen.
Verwenden Sie venv für gewöhnliche Python Übungen ohne native GDAL-Anforderungen.
Installieren Sie conda Abhängigkeiten vor pip-only Paketen und überprüfen Sie Importe.
Behalten Sie geprüfte Spezifikationen und validieren Sie Updates mit den Kurs Notebooks.
Halten Sie Jupyter Buch Autorisierung getrennt von der rechnerischen Kursumgebung.