Enable Linux compatibility with dependency changes and improved dev t…

…ooling (#17)

* run linux tests on dev branch

* don't show if headless

* install qt deps

* try async setting

* Update run-tests.yml

* try additional qt libs

* troubleshoot further with docker

* linting

* Update run-tests.yml

* Update run-tests.yml

* Update run-tests.yml

* Update uv.lock

* fallback to napari[all] and setup qt for ubuntu

* move to macos-14 for tests

* add python3-pyqt5 installation

* attempt to install different qt deps

* Update run-tests.yml

* attempt another linux dep step

* update for linting step

* update docs

.github/workflows/run-tests.yml

@@ -10,7 +10,7 @@ on:
 
 jobs:
   pre_commit_checks:
-    runs-on: macos-13
+    runs-on: ubuntu-22.04
     steps:
       # checks out the repo
       - uses: actions/checkout@v4
@@ -21,6 +21,10 @@ jobs:
           python-version: "3.11"
       - name: Install the latest version of uv
         uses: astral-sh/setup-uv@v5
+      - name: Display configuration for Ubuntu
+        uses: pyvista/setup-headless-display-action@v3
+        with:
+          qt: true
       - uses: pre-commit/[email protected]
       # run pre-commit ci lite for automated fixes
       - uses: pre-commit-ci/[email protected]
@@ -29,7 +33,7 @@ jobs:
     strategy:
       matrix:
         python_version: ["3.11", "3.12"]
-        os: [macos-13]
+        os: [ubuntu-22.04, macos-14]
     runs-on: ${{ matrix.os }}
     env:
       OS: ${{ matrix.os }}
@@ -40,6 +44,11 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python_version }}
+      - name: Display configuration for Ubuntu
+        if: ${{ matrix.os == 'ubuntu-22.04' }}
+        uses: pyvista/setup-headless-display-action@v3
+        with:
+          qt: true
       - name: Install the latest version of uv
         uses: astral-sh/setup-uv@v5
       - name: Run pytest

.pre-commit-config.yaml

@@ -23,7 +23,7 @@ repos:
     hooks:
     -   id: validate-cff
 -   repo: https://github.com/codespell-project/codespell
-    rev: v2.4.0
+    rev: v2.4.1
     hooks:
     -   id: codespell
         exclude: |
@@ -45,7 +45,7 @@ repos:
     -   id: yamllint
         exclude: pre-commit-config.yaml
 -   repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.9.3"
+    rev: "v0.9.4"
     hooks:
     -   id: ruff-format
     -   id: ruff

Dockerfile

@@ -0,0 +1,43 @@
+# referenced with modifications from
+# https://github.com/napari/napari/blob/main/dockerfile
+FROM --platform=linux/amd64 python:3.11 AS napari
+
+# below env var required to install libglib2.0-0 non-interactively
+ENV TZ=America/Los_Angeles
+ARG DEBIAN_FRONTEND=noninteractive
+ARG NAPARI_COMMIT=main
+
+WORKDIR /nviz
+
+# install python resources + graphical libraries used by qt and vispy
+RUN apt-get update && \
+    apt-get install -qqy  \
+        build-essential \
+        git \
+        mesa-utils \
+        x11-utils \
+        libegl1-mesa \
+        libopengl0 \
+        libgl1-mesa-glx \
+        libglib2.0-0 \
+        libfontconfig1 \
+        libxrender1 \
+        libdbus-1-3 \
+        libxkbcommon-x11-0 \
+        libxi6 \
+        libxcb-icccm4 \
+        libxcb-image0 \
+        libxcb-keysyms1 \
+        libxcb-randr0 \
+        libxcb-render-util0 \
+        libxcb-xinerama0 \
+        libxcb-xinput0 \
+        libxcb-xfixes0 \
+        libxcb-shape0 \
+        && apt-get clean
+
+# install napari from repo
+# see https://github.com/pypa/pip/issues/6548#issuecomment-498615461 for syntax
+RUN pip install --upgrade pip
+
+ENTRYPOINT ["/bin/bash"]

README.md

@@ -27,6 +27,17 @@ pip install nviz
 pip install git+https://github.com/WayScience/nViz.git
 ```
 
+### Installation notes for Linux
+
+`nViz` leverages Napari to help render visuals.
+Napari leverages [PyQT](https://riverbankcomputing.com/software/pyqt/intro) to help build graphical components.
+PyQT has specific requirements based on the operating system which sometimes can cause errors within Napari, and as a result, also `nViz`.
+
+Below are some steps to try if you find that `nViz` visualizations through Napari are resulting in QT-related errors.
+
+- Attempt to install `python3-pyqt5` through your system package manager (e.g. `apt install python3-pyqt5`).
+- When using `nViz` within GitHub Actions Linux environments, consider using [pyvista/setup-headless-display-action](https://github.com/pyvista/setup-headless-display-action) with `qt: true` in order to run without general exceptions.
+
 ## Contributing, Development, and Testing
 
 Please see our [contributing](https://WayScience.github.io/coSMicQC/main/contributing) documentation for more details on contributions, development, and testing.

pyproject.toml

@@ -35,6 +35,7 @@ dev = [
   "jupytext>=1.16.6",
   "myst-nb>=1.1.2",
   "myst-parser>=4",
+  "poethepoet>=0.32.2",
   "pre-commit>=4.0.1",
   "pydata-sphinx-theme>=0.16.1",
   "pytest>=8.3.4",
@@ -89,3 +90,12 @@ formats = "ipynb,py:light"
 [tool.vulture]
 min_confidence = 90
 paths = [ "src/nviz", "tests" ]
+
+[tool.poe.tasks]
+# Create a local docker image and run it
+# with this directory mapped to /nviz
+# for development within linux environments.
+docker-run.shell = """
+docker build --platform linux/amd64 -t nviz:latest -f tests/Dockerfile .
+docker run --platform linux/amd64 -it --rm -v $PWD:/nviz nviz
+"""