Update and expand examples

.github/workflows/test.yml

@@ -0,0 +1,49 @@
+name: Test
+
+on:
+  push:
+  pull_request:
+  schedule:
+    - cron: '31 4 3 * *'  # 4:31a on third day of the month
+
+concurrency:
+  group: ${{ github.ref }}-${{ github.workflow }}
+  cancel-in-progress: true
+
+jobs:
+
+  test:
+    name: Run tests
+    if:
+      github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository
+
+    runs-on: ${{ matrix.os }}
+
+    defaults:
+      run:
+        shell: bash -l {0}
+
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install requirements
+        run: pip install pytest nbmake -r examples/requirements.txt
+
+      - name: Check example script
+        working-directory: ${{ github.workspace }}/examples
+        run: |
+          python run-model-through-grpc4bmi.py
+
+      - name: Check example notebook
+        run: |
+          pytest examples --nbmake --nbmake-timeout=3000 -v

README.md

@@ -1,8 +1,13 @@
+[![Basic Model Interface](https://img.shields.io/badge/CSDMS-Basic%20Model%20Interface-green.svg)](https://bmi.readthedocs.io/)
+[![Test](https://github.com/csdms/bmi-example-python-grpc4bmi/actions/workflows/test.yml/badge.svg)](https://github.com/csdms/bmi-example-python-grpc4bmi/actions/workflows/test.yml)
+[![Docker Hub](https://github.com/csdms/bmi-example-python-grpc4bmi/actions/workflows/release.yml/badge.svg)](https://github.com/csdms/bmi-example-python-grpc4bmi/actions/workflows/release.yml)
+![Docker Image Version](https://img.shields.io/docker/v/csdms/bmi-example-python-grpc4bmi)
+
 # bmi-example-python-grpc4bmi
 
 Set up a [grpc4bmi](https://grpc4bmi.readthedocs.io) server
 to run a containerized version
-of the [Basic Model Interface](https://bmi.readthedocs.io)
+of the [Basic Model Interface](https://bmi.readthedocs.io) (BMI)
 [Python example](https://github.com/csdms/bmi-example-python).
 
 ## Build
@@ -11,19 +16,18 @@ Build the server image locally with:
 ```
 docker build --tag bmi-example-python-grpc4bmi .
 ```
-The image is built on the [csdms/bmi-example-python](https://hub.docker.com/r/csdms/bmi-example-python) image.
+The image is built on the [csdms/grpc4bmi](https://hub.docker.com/r/csdms/grpc4bmi) base image,
+which is built on the [condaforge/miniforge3](https://hub.docker.com/r/condaforge/miniforge3) base image.
 The OS is Linux/Ubuntu.
-`conda` and `mamba` are installed in `CONDA_DIR=opt/conda`,
-and the *base* environment is activated,
 The grpc4bmi Python server,
-as well as the Python BMI specification and example
+as well as the Python BMI mappings and example
 (consisting of the *Heat* model and a BMI implementation, *BmiHeat*)
-are installed into it.
+are installed in `CONDA_DIR=/opt/conda`.
 
 ## Run
 
-Use the grpc4bmi [Docker client](https://grpc4bmi.readthedocs.io/en/latest/container/usage.html#docker)
-to access the BMI methods of the containerized model.
+Use the grpc4bmi Docker client to access the BMI methods of the containerized model.
+
 Install grpc4bmi with *pip*:
 ```
 pip install grpc4bmi
@@ -42,7 +46,7 @@ del m  # stop container cleanly
 If the image isn't found locally, it's pulled from Docker Hub
 (e.g., try substituting `IMAGE_NAME="csdms/bmi-example-python-grpc4bmi"` above).
 
-For a more in-depth example of running the *Heat* model from grpc4bmi,
+For more in-depth examples of running the *Heat* model from grpc4bmi,
 see the [examples](./examples) directory.
 
 ## Developer notes
@@ -65,7 +69,7 @@ optionally with the `latest` tag or with a version tag.
 ## What are the Basic Model Interface and grpc4bmi?
 
 The Basic Model Interface (BMI) is a set of functions for querying, modifying, running, and coupling models.
-Learn more at https://bmi.readthedocs.io/.
+Learn more at https://bmi.csdms.io/.
 
 grpc4bmi is a [gRPC](https://grpc.io/) wrapper for a model with a BMI.
 Learn more at https://grpc4bmi.readthedocs.io/.

examples/README.md

@@ -0,0 +1,22 @@
+# examples
+
+Two examples--a [Python script](./run-model-through-grpc4bmi.py)
+and a [Jupyter notebook](./run-model-through-grpc4bmi.ipynb)--that demonstrate how to run
+the containerized Python `Heat` model through the grpc4bmi server built in this project.
+
+In a virtual environment,
+install grpc4bmi and other dependencies:
+```sh
+pip install -r requirements.txt
+```
+
+Run the Python example:
+```sh
+python run-model-through-grpc4bmi.py
+```
+It'll produce output in the terminal.
+
+Start JupyterLab and run the example notebook:
+```sh
+jupyter lab run-model-through-grpc4bmi.ipynb
+```

examples/requirements.txt

@@ -0,0 +1,2 @@
+grpc4bmi
+jupyter