Skip to content

fix: use qtpy instead of importing PyQt5 directly - #40

Merged
hongquanli merged 3 commits into
mainfrom
fix/pyqt6-qtpy-migration
Nov 7, 2026
Merged

hongquanli merged 3 commits into
mainfrom
fix/pyqt6-qtpy-migration

Conversation

@hongquanli

Copy link
Copy Markdown
Collaborator

Problem

ndviewer_light imports PyQt5 directly. Squid embeds this viewer in its own process, and since the napari 0.7 migration (Cephla-Lab/Squid#622) that process is PyQt6-only, so every import fails:

ERROR squid.NDViewerTab: Failed to import ndviewer_light: No module named 'PyQt5'

The NDViewer tab then silently degrades to NDViewer tab unavailable: ndviewer_light module not installed (gui_hcs.py:1226).

Installing PyQt5 alongside is not an option — two Qt bindings in one environment break napari/vispy OpenGL rendering, which setup_22.04.sh calls out explicitly:

Exactly ONE Qt binding may be installed — PyQt5 and PyQt6 in the same environment conflict and break napari/vispy OpenGL rendering.

This is not platform-specific: anyone following setup_22.04.sh on Ubuntu gets a PyQt6-only environment and hits it identically.

Change

Import through qtpy and let the host application supply the binding.

  • ndviewer_light/core.py, simulate_push_acquisition.py, simulate_zarr_acquisition.py, tests/test_3d_visualization.py — PyQt5.* → qtpy.*
  • pyproject.toml / environment.yml — declare qtpy instead of pyqt5

Two details worth noting:

  • qtpy exposes Signal, not pyqtSignal, so the two signal declarations in core.py were renamed accordingly.
  • qtpy promotes unscoped enums under PyQt6, so Qt.AlignCenter-style access needed no changes — this is why the diff is as small as it is.

Verification

Under Python 3.12 / PyQt6 6.11.0 / napari 0.7.1:

  • import ndviewer_light succeeds with qtpy.API_NAME == "PyQt6"
  • Squid's test_widgets.py goes from 4 failures to 158 passed
  • Squid GUI starts with no ndviewer/PyQt5 errors in the log

Requires tensorstore at import time, which Squid's setup script installs as of Cephla-Lab/Squid#622.

Squid runs this viewer embedded in its own process, which is PyQt6-only since
the napari 0.7 migration, so `from PyQt5...` raised ImportError and the
NDViewer tab failed to load. Installing PyQt5 alongside is not an option: two
Qt bindings in one environment break napari/vispy OpenGL rendering.

qtpy promotes unscoped enums under PyQt6, so Qt.AlignCenter-style access is
unchanged; only pyqtSignal needed renaming to Signal. The declared dependency
is now qtpy rather than a concrete binding, which the host application supplies.
qtpy resolves a binding at import time and raises QtBindingsNotFoundError when
none is installed, so replacing the pyqt5 dependency with qtpy alone broke every
standalone use: CI collected 14 import errors, and the simulate_* scripts would
fail the same way.

Embedded in Squid the host process already supplies PyQt6, which is why a
concrete binding must not be a hard dependency here -- a second binding in that
environment breaks napari/vispy OpenGL rendering. So it is an extra,
`pip install .[pyqt6]`, mirroring napari[pyqt6], and environment.yml (used by CI
and for standalone work) installs PyQt6 explicitly.
@hongquanli

Copy link
Copy Markdown
Collaborator Author

Merged main (after #42) into this branch: clean auto-merge, suite 286 passed with qtpy resolving to PyQt5, black clean. Merging now; the ndv 0.5 port follows on top of this.

@hongquanli
hongquanli merged commit df01b6e into main Nov 7, 2026
1 of 2 checks passed
hongquanli added a commit that referenced this pull request Nov 7, 2026
…) (#43)

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
hongquanli added a commit that referenced this pull request Nov 8, 2026
…needs [pyqt6] (#46)

* docs: one-line Windows install; standalone install needs the [pyqt6] extra

- README: a PowerShell one-liner for Windows (clone, venv, install with the
  [pyqt6] extra, desktop shortcut), with how to update and run from a
  terminal and why it uses `py` (a fresh Windows's `python` is a Store stub).
- README: the standalone snippet installed `.` without a Qt binding; since
  #40 qtpy is the only Qt dependency, so it could not open a window. It now
  installs ".[pyqt6]", as the Requirements section already says.
- README: Windows test commands (PYTHONUTF8 for two tests that read source
  files with the default encoding; QT_QPA_PLATFORM=windows for real GL) and
  the two tests that fail on Windows only (they expect `/` in paths).
- create_shortcut.py: prefer the `ndviewer-light` next to the running
  interpreter over the first one on PATH, so running the script with a
  venv's python (as the one-liner does, without activating it) points the
  shortcut at that venv's launcher instead of falling back to
  `python -m ndviewer_light`. tests/test_create_shortcut.py covers the
  order: next to the interpreter, then PATH, then `python -m`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test: pass on Windows without UTF-8 mode or known failures

- test_existing_field_without_metadata_is_broken and
  test_broken_fov_fails_the_load expected `B/3/0` in error messages, which
  name the field by its filesystem path (`B\3\0` on Windows). They now
  build the expected fragment with pathlib, so the message is still
  checked for the field on every OS.
- test_3d_scales.py and test_channel_names.py read core.py with the locale
  encoding (cp1252 on Windows), which fails on its non-ASCII characters;
  they now read it as UTF-8.
- README: drop the PYTHONUTF8 step and the known-failures note.

Windows, run as the README says: offscreen 312 passed / 3 skipped; real GL
315 passed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: shortcut targets the venv launcher even with one in the current directory

shutil.which(path=...) on Windows Python <= 3.11 still searches the current
directory first, so a stray ndviewer-light.exe there won over the running
interpreter's sibling launcher. Check the sibling path directly, then fall
back to PATH, then to `python -m ndviewer_light`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant