Refactor Ribasim Python (#114)

Python:
- Added CI
- Added dev docs
- Extended README
- Fixed ruff lints
- Removed tox
- Extended environment.yml

Rest:
 - Renamed CI workflows
 - Limited cases where certain workflows are run

.github/workflows/CompatHelper.yml → .github/workflows/core_compat_helper.yml

@@ -1,4 +1,4 @@
-name: CompatHelper
+name: Julia CompatHelper
 on:
   schedule:
     - cron: 0 0 * * *

.github/workflows/CI.yml → .github/workflows/core_tests.yml

@@ -1,18 +1,18 @@
-name: CI
+name: Julia Tests
 on:
   push:
     branches: [main]
     tags: ["*"]
-    paths-ignore: [".teamcity/**"]
+    paths: [".github", "core"]
   pull_request:
 jobs:
   test:
-    name: Julia CI ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
+    name: Julia ${{ matrix.julia_version }} - ${{ matrix.os }} - ${{ matrix.arch }}
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
-        version:
+        julia_version:
           - "1.8"
         os:
           - ubuntu-latest
@@ -28,7 +28,7 @@ jobs:
       - uses: actions/checkout@v2
       - uses: julia-actions/setup-julia@v1
         with:
-          version: ${{ matrix.version }}
+          version: ${{ matrix.julia_version }}
           arch: ${{ matrix.arch }}
       - uses: actions/cache@v1
         env:

.github/workflows/docs.yml

@@ -1,25 +1,28 @@
-name: docs
+name: Docs
 on:
   push:
     branches: [main]
+    paths-ignore: [".teamcity/**"]
   pull_request:
 jobs:
   publish:
-    name: Julia Docs ${{ matrix.version }} - ${{ matrix.arch }} - ${{ github.event_name }}
+    name: Docs Julia ${{ matrix.julia_version }} - Python ${{ matrix.python_version }}  - ${{ matrix.arch }}
     runs-on: ubuntu-latest
     permissions:
       contents: write
     strategy:
       matrix:
-        version:
-          - "1.8" # make sure to keep this in sync with _quarto.yml
+        julia_version:
+          - "1.8"
+        python_version:
+          - "3.11"
         arch:
           - x64
     steps:
       - uses: actions/checkout@v3
       - uses: julia-actions/setup-julia@v1
         with:
-          version: ${{ matrix.version }}
+          version: ${{ matrix.julia_version }}
           arch: ${{ matrix.arch }}
       - uses: julia-actions/julia-buildpkg@v1
         with:
@@ -37,7 +40,7 @@ jobs:
       # setup Python / Jupyter
       - uses: actions/setup-python@v4
         with:
-          python-version: '3.11'
+          python-version: "${{ matrix.python_version }}"
       - run: pip install jupyter quartodoc xarray
 
       - name: Install ribasim-python

.github/workflows/python_lint.yml

@@ -0,0 +1,43 @@
+name: Python Lint
+on:
+  push:
+    branches: [main]
+    tags: ["*"]
+    paths: [".github", "python"]
+  pull_request:
+jobs:
+  lint:
+    name: Python ${{ matrix.python_version }} - ${{ matrix.os }} - ${{ matrix.arch }}
+    continue-on-error: true
+    runs-on: ${{ matrix.os }}
+    defaults:
+      run:
+        shell: bash -l {0}
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest
+        arch:
+          - x64
+        python_version:
+          - "3.11"
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Micromamba
+        uses: mamba-org/provision-with-micromamba@main
+        with:
+          python_version: ${{ matrix.python_version }}
+          cache-downloads: true
+          cache-env: true
+          environment-file: ./python/environment.yml
+
+      - name: Run black
+        working-directory: python
+        run: black --check .
+
+      # Include `--format=github` to enable automatic inline annotations.
+      - name: Run ruff
+        working-directory: python
+        run: ruff check --format=github .

.github/workflows/python_tests.yml

@@ -0,0 +1,45 @@
+name: Python Tests
+on:
+  push:
+    branches: [main]
+    tags: ["*"]
+    paths: [".github", "python"]
+  pull_request:
+jobs:
+  test:
+    name: Python ${{ matrix.python_version }} - ${{ matrix.os }} - ${{ matrix.arch }}
+    runs-on: ${{ matrix.os }}
+    defaults:
+      run:
+        shell: bash -l {0}
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest
+          - macOS-latest
+          - windows-latest
+        python_version:
+          - "3.9"
+          - "3.10"
+          - "3.11"
+        arch:
+          - x64
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Micromamba
+        uses: mamba-org/provision-with-micromamba@main
+        with:
+          python_version: ${{ matrix.python_version }}
+          cache-downloads: true
+          cache-env: true
+          environment-file: ./python/environment.yml
+
+      - name: Install ribasim
+        working-directory: python
+        run: pip install -e .
+
+      - name: Run tests
+        working-directory: python
+        run: pytest tests

.github/workflows/typos.yml

@@ -1,4 +1,4 @@
-name: typos
+name: Typos
 on:
   push:
     branches: [main]

.gitignore

@@ -19,7 +19,6 @@ docs/site/
 build/create_binaries/ribasim_cli/
 build/create_binaries/libribasim/
 
-.vscode
 JuliaSysimage.dll
 LocalPreferences.toml
 .ipynb_checkpoints
@@ -153,5 +152,5 @@ dmypy.json
 # Pyre type checker
 .pyre/
 
-# VS Code settings
-*.vscode
+# vscode
+.vscode/settings.json

.vscode/extensions.json

@@ -0,0 +1,8 @@
+{
+    "recommendations": [
+        "julialang.language-julia",
+        "ms-python.python",
+        "charliermarsh.ruff",
+        "njpwerner.autodocstring"
+    ]
+}

.vscode/settings_template.json

@@ -0,0 +1,16 @@
+{
+    "[julia]": {
+        "editor.formatOnSave": true
+    },
+    "julia.environmentPath": "core",
+    "[python]": {
+        "editor.formatOnSave": true,
+        "editor.codeActionsOnSave": {
+            "source.fixAll": true
+        }
+    },
+    "python.formatting.provider": "black",
+    "python.linting.mypyEnabled": true,
+    "python.linting.enabled": true,
+    "cSpell.enabled": false,
+}

docs/_quarto.yml

@@ -32,6 +32,7 @@ website:
         - python/index.qmd
         - python/examples.ipynb
         - python/reference/index.qmd
+        - python/developer.qmd
     - title: "Coupled models"
       contents:
         - couple/index.qmd

docs/python/developer.qmd

@@ -0,0 +1,67 @@
+---
+title: "For developers"
+---
+
+# Set up the developer environment
+
+## Setting up conda
+
+In order to develop on `ribasim` locally, please follow the following steps:
+
+- Download and install [miniconda](https://docs.conda.io/en/latest/miniconda.html).
+
+- Initialize `conda` by running the following in the `Miniconda prompt`:
+
+```
+conda init
+```
+
+- Depending on your company settings, you might also have to run the following in a Powershell terminal as administrator:
+
+```
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned
+```
+
+## Creating (or updating) the environment
+
+- Create (or update) the environment by executing the following in your terminal:
+
+```
+conda env create --file=environment.yml --force
+```
+
+## Installing Ribasim Python
+
+- Activate the environment
+
+```
+conda activate ribasim
+```
+
+In order to develop on `ribasim` locally, execute the following line inside your virtual environment
+
+```bash
+pip install -e .
+```
+
+## Running the tests
+
+
+If no already done, activate the environment
+
+```
+conda activate ribasim
+```
+
+
+To run the tests execute:
+
+```bash
+pytest tests
+```
+
+## Setup Visual Studio Code (optional)
+
+1. Install the [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python), [ruff](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff) and [autoDocstring](https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring) extensions.
+
+2. Copy `.vscode/settings_template.json` into `.vscode/settings.json`

python/README.md

@@ -0,0 +1,20 @@
+# Ribasim Python
+
+The Ribasim Python package (named `ribasim`) aims to make it easy to build, update and analyze Ribasim models
+programmatically.
+
+The Ribasim QGIS plugin allows users to construct a model from scratch without programming.
+For specific tasks, like adding observed rainfall timeseries, it can be faster to use
+Python instead.
+
+One can also use Ribasim Python to build entire models from base data, such that your model
+setup is fully reproducible.
+
+The package is [registered in PyPI](https://pypi.org/project/ribasim/) and can therefore
+be installed with `pip install ribasim`.
+
+For documentation please see the [examples](https://deltares.github.io/Ribasim/python/examples.html) and [API reference](https://deltares.github.io/Ribasim/python/reference/).
+
+# Contributing
+
+For the developer docs please have a look at https://deltares.github.io/Ribasim/python/developer.html

python/environment.yml

@@ -4,15 +4,19 @@ channels:
   - conda-forge
 
 dependencies:
-  - python >= 3.9
+  - black
+  - geopandas
   - matplotlib
+  - mypy
   - pandas
-  - geopandas
   - pandera
   - pyarrow
   - pydantic
   - pyogrio
-  - shapely >=2.0
+  - python>3.9
+  - pytest
+  - ruff
+  - shapely>=2.0
   - tomli
   - tomli-w
   - xarray