python-environment-manager

Python Environment Manager

Set up and manage ras-commander Python environments. Handle environment creation, validation, troubleshooting, and upgrades.

Key Decision: No Editable Install for Development

CRITICAL: The rascmdr_local environment does NOT use pip install -e .

Instead, use a toggle cell in Jupyter notebooks that manipulates sys.path to load local source code. This approach:

• Guarantees local source is always loaded (even if pip package exists)
• Remains simple to understand and explain
• Works reliably across all environments
• Can be toggled with a single variable

Why sys.path.insert(0, ...) Works

Python searches sys.path in order (index 0 first). By inserting the local repo path at position 0:

1. Python finds ras_commander/ in the repo first
2. The pip-installed package (if any) is never reached
3. 100% guaranteed local source loading

Standard Environment Names

RasCommander (User Environment)

Purpose: Standard user environment with pip package

When to use:

• Running example notebooks as an end user
• Using ras-commander for HEC-RAS automation
• NOT editing ras-commander source code

Setup:

conda create -n RasCommander python=3.13
conda activate RasCommander
pip install ras-commander
pip install jupyter ipykernel
python -m ipykernel install --user --name RasCommander --display-name "Python (RasCommander)"

rascmdr_local (Development Environment)

Purpose: Development environment with dependencies only (NO ras-commander pip install)

When to use:

• Editing ras-commander source code
• Contributing to the library
• Testing code changes immediately

Setup:

conda create -n rascmdr_local python=3.13
conda activate rascmdr_local

# Install DEPENDENCIES ONLY - NOT ras-commander itself
pip install h5py numpy pandas geopandas matplotlib shapely scipy xarray tqdm requests rasterstats rtree pyproj fiona

# Install Jupyter
pip install jupyter ipykernel
python -m ipykernel install --user --name rascmdr_local --display-name "Python (rascmdr_local)"