create test and pylint CI workflows; use devops_tests as a submodule; add show_anim(); bump checkout & setup-python actions in pylint CI job; move more setup entries into pyproject.toml; add example notebook with animation

.github/workflows/pylint.yml

@@ -12,14 +12,14 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v2
-    - name: Set up Python 3.9
-      uses: actions/setup-python@v2
+    - uses: actions/checkout@v4
+    - name: Set up Python 3.12
+      uses: actions/setup-python@v5
       with:
-        python-version: 3.9
+        python-version: 3.12
     - name: Install dependencies
       run: |
-        python -m pip install --upgrade pip
+        python -m pip install --upgrade pip setuptools
         pip install pylint
         python setup.py egg_info
         pip install -r *.egg-info/requires.txt

.github/workflows/tests.yml

@@ -0,0 +1,26 @@
+name: tests
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+      branches: [ main ] 
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: true
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.12
+      - name: Run tests
+        run: |
+          pip install -e .
+          pip install -r tests/devops_tests/requirements.txt
+          pytest -vv -rP -We tests/devops_tests/test_notebooks.py::test_run_notebooks

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "tests/devops_tests.git"]
+	path = tests/devops_tests
+	url = [email protected]:open-atmos/devops_tests.git

README.md

@@ -6,6 +6,7 @@
 
 Utility routines used in Jupyter notebooks in [PySDM](https://github.com/open-atmos/PySDM), [PyMPDATA](https://github.com/open-atmos/PyMPDATA) and [PyPartMC](https://github.com/open-atmos/PyPartMC) projects:
 - [``show_plot()``](https://open-atmos.github.io/jupyter-utils/open_atmos_jupyter_utils/show_plot.html) - a drop-in replacement for matplotlib's show() displaying the figure inline using vector graphics (svg) by default and offering a download-as-pdf-or-svg widget just below (on Colab the widget triggers Google Drive download)
+- [``show_anim()``](https://open-atmos.github.io/jupyter-utils/open_atmos_jupyter_utils/show_anim.html) - a replacement for matplotlib's FuncAnimate() that inline-displays animations in gif format (thus github renderer compatible) and offers a way to download the .gif file (on Colab the widget triggers Google Drive download) 
 - [``TemporaryFile``](https://open-atmos.github.io/jupyter-utils/open_atmos_jupyter_utils/temporary_file.html) - a class equipped with ``make_link_widget()`` method returning a click-to-download Colab-compatible widget to be display()-ed in a Jupyter notebook
 - [``pip_install_on_colab('package_a', 'package_b', ...)``](https://open-atmos.github.io/jupyter-utils/open_atmos_jupyter_utils/pip_install_on_colab.html) - a function handling execution of ``pip`` (and ``ldconfig``) on Colab 
 

open_atmos_jupyter_utils/show_anim.py

@@ -0,0 +1,38 @@
+"""inline animation function that allows rendering on github
+ preview and showing click to download gif button"""
+
+#pylint: disable=consider-using-with
+import os
+import tempfile
+import base64
+import imageio
+import matplotlib.pyplot as plt
+from IPython.display import HTML, display
+from open_atmos_jupyter_utils.temporary_file import TemporaryFile
+
+
+def show_anim(plot_func, frame_range, duration=0.01, loop=0):
+    """plot_func is called with one argument - the frame number from frame_range
+    and is expected to return a matplotlib figure instance (on which savefig()
+    and close() are subsequently called)"""
+    gif_file = TemporaryFile(suffix=".gif")
+    with tempfile.TemporaryDirectory() as tmpdirname:
+        for frame in frame_range:
+            fig = plot_func(frame)
+            fig.savefig(f"{tmpdirname}/{frame:05d}.png")
+            plt.close(fig)
+        __merge_images_into_gif(tmpdirname, gif_file, duration, loop)
+
+        b64 = base64.b64encode(open(gif_file.basename,'rb').read()).decode("ascii")
+        display(HTML(f'<img src="data:image/gif;base64,{b64}" />'))
+        display(gif_file.make_link_widget())
+
+
+def __merge_images_into_gif(image_folder, gif_name, duration, loop):
+    """creates a GIF file from a series of animation frames"""
+    with imageio.get_writer(
+        gif_name.basename, duration=duration, loop=loop, mode="I"
+    ) as writer:
+        for filename in sorted(os.listdir(image_folder)):
+            image = imageio.v3.imread(os.path.join(image_folder, filename))
+            writer.append_data(image)

pyproject.toml

@@ -1,9 +1,24 @@
+[tool.setuptools]
+
 [tool.setuptools_scm]
 
 # TODO
 [build-system]
-requires = ['setuptools==56.0.0', 'setuptools-scm==6.0.1']
+requires = ['setuptools==75.3.0', 'setuptools-scm==8.1.0']
+build-backend = "setuptools.build_meta"
 
+[project]
+name = 'open-atmos-jupyter-utils'
+description = "utility routines used in PySDM, PyMPDATA and PyPartMC examples and tests"
+license = {text = "GPL-3.0"}
+readme = "README.md"
+dynamic = ["version"]
+dependencies = [
+    "ipywidgets",
+    "IPython",
+    "matplotlib",
+    "imageio",
+]
 [project.urls]
 "Homepage" = "https://github.com/open-atmos/jupyter-utils"
 "Source" = "https://github.com/open-atmos/jupyter-utils"

setup.py

@@ -1,6 +1,7 @@
 """
 the magick behind ``pip install ...``
 """
+
 from setuptools import setup, find_packages
 
 
@@ -12,19 +13,13 @@ def get_long_description():
 
 
 setup(
-    name='open-atmos-jupyter-utils',
-    description='utility routines used in PySDM, PyMPDATA and PyPartMC examples and tests',
-    use_scm_version={
-        "local_scheme": lambda _: "",
-        "version_scheme": "post-release"
-    },
-    setup_requires=['setuptools_scm'],
-    install_requires=['ipywidgets', 'IPython', 'matplotlib'],
-    author='https://github.com/open-atmos/jupyter-utils/graphs/contributors',
-    author_email='[email protected]',
-    license="GPL-3.0",
-    packages=find_packages(include=['open_atmos_jupyter_utils', 'open_atmos_jupyter_utils.*']),
+    use_scm_version={"local_scheme": lambda _: "", "version_scheme": "post-release"},
+    setup_requires=["setuptools_scm", "setuptools"],
+    install_requires=["ipywidgets", "IPython", "matplotlib", "imageio"],
+    packages=find_packages(
+        include=["open_atmos_jupyter_utils", "open_atmos_jupyter_utils.*"]
+    ),
     long_description=get_long_description(),
     long_description_content_type="text/markdown",
-    url='https://github.com/open-atmos/jupyter-utils',
+    url="https://github.com/open-atmos/jupyter-utils",
 )