huge diff: refactor to include utilities container and more settings (#35)

xref: ndev-kit/napari-ndev#210

1. Rip out Utilities Container from napari-ndev
2. Move helpers from napari-ndev to here <- this needs refactored out
completely later
3. Update settings 
4. update some pyproject config / pre-commit to fix things
5. lazy imports to improve import time (2.5s to 15ms, but nImage still
pulls in BioImage which is ~2s)
6. fix and add tests, but nothing is "broken" re: legacy code

## Copilot explanation

This pull request introduces several improvements and updates across the
codebase, focusing on standardizing configuration naming, expanding
settings for export functionality, enhancing dependency management, and
adding new utility functions. The changes also improve documentation and
developer experience.

### Configuration and Settings Standardization

* Renamed all references of `ndevio_Reader` to `ndevio_reader` in
settings, code, and documentation for consistency and clarity. This
affects YAML files, code logic, and markdown documentation.
[[1]](diffhunk://#diff-a54ff182c7e8acf56acfd6e4b9c3ff41e2c41a31c9b211b2deb9df75d9a478f9L98-R98)
[[2]](diffhunk://#diff-a54ff182c7e8acf56acfd6e4b9c3ff41e2c41a31c9b211b2deb9df75d9a478f9L285-R285)
[[3]](diffhunk://#diff-a54ff182c7e8acf56acfd6e4b9c3ff41e2c41a31c9b211b2deb9df75d9a478f9L311-R311)
[[4]](diffhunk://#diff-a54ff182c7e8acf56acfd6e4b9c3ff41e2c41a31c9b211b2deb9df75d9a478f9L565-R565)
[[5]](diffhunk://#diff-a1495b29f6e07c8278a427f1ad3f4b1033da9353d263c050f0c8d9ac1b2aeebdL54-R60)
[[6]](diffhunk://#diff-a1495b29f6e07c8278a427f1ad3f4b1033da9353d263c050f0c8d9ac1b2aeebdL81-R81)
[[7]](diffhunk://#diff-11c9170a9cc22a07c8e3347c1210ae7bfb99877cba412ab3d5d79f7c691c9f09L1-R1)
[[8]](diffhunk://#diff-11c9170a9cc22a07c8e3347c1210ae7bfb99877cba412ab3d5d79f7c691c9f09R29-R48)
[[9]](diffhunk://#diff-e483cf7e2129edce2bdf6c16f9e6bb60e0716ee89b8d788206109cdd6d782c3fL37-R35)
[[10]](diffhunk://#diff-e483cf7e2129edce2bdf6c16f9e6bb60e0716ee89b8d788206109cdd6d782c3fL62-R61)
[[11]](diffhunk://#diff-e483cf7e2129edce2bdf6c16f9e6bb60e0716ee89b8d788206109cdd6d782c3fL71-R70)
[[12]](diffhunk://#diff-e483cf7e2129edce2bdf6c16f9e6bb60e0716ee89b8d788206109cdd6d782c3fL277-R278)

* Added new export-related settings under `ndevio_export` to
`ndev_settings.yaml`, enabling control over canvas scaling, size, and
override behavior for exported figures and screenshots.

### Dependency and Environment Updates

* Updated dependencies in `pyproject.toml`: pinned `ndev-settings` to
version `>=0.4.0`, added new packages (`napari`, `nbatch`, `natsort`,
`magicgui`, `magic-class`), and included `bioio-czi` for
development/testing. Also set a minimum coverage threshold for tests.
[[1]](diffhunk://#diff-50c86b7ed8ac2cf95bd48334961bf0530cdc77b5a56f852c5c61b89d735fd711L31-R44)
[[2]](diffhunk://#diff-50c86b7ed8ac2cf95bd48334961bf0530cdc77b5a56f852c5c61b89d735fd711R60)
[[3]](diffhunk://#diff-50c86b7ed8ac2cf95bd48334961bf0530cdc77b5a56f852c5c61b89d735fd711R91-R93)

* Modified `.pre-commit-config.yaml` to exclude
`src/ndevio/ndev_settings.yaml` from YAML syntax checks and updated the
`ndev-settings` hook to use version `0.4.0`.
[[1]](diffhunk://#diff-63a9c44a44acf85fea213a857769990937107cf072831e1a26808cfde9d096b9R10-R11)
[[2]](diffhunk://#diff-63a9c44a44acf85fea213a857769990937107cf072831e1a26808cfde9d096b9L23-R25)

### Utilities and API Enhancements

* Added a new `helpers.py` module with utility functions for file
handling and image processing, such as directory scanning, channel name
extraction, dimension order calculation, ID string creation, missing
file checking, and string elision.

* Updated `__init__.py` to support lazy loading of `nImage` and expose
the new `helpers` module in the public API.

### Documentation and Developer Experience

* Improved documentation in `AGENTS.md` to reflect configuration changes
and updated installation instructions to use the correct `uv pip`
command for development dependencies.
[[1]](diffhunk://#diff-a54ff182c7e8acf56acfd6e4b9c3ff41e2c41a31c9b211b2deb9df75d9a478f9L22-R22)
[[2]](diffhunk://#diff-a54ff182c7e8acf56acfd6e4b9c3ff41e2c41a31c9b211b2deb9df75d9a478f9L98-R98)
[[3]](diffhunk://#diff-a54ff182c7e8acf56acfd6e4b9c3ff41e2c41a31c9b211b2deb9df75d9a478f9L285-R285)
[[4]](diffhunk://#diff-a54ff182c7e8acf56acfd6e4b9c3ff41e2c41a31c9b211b2deb9df75d9a478f9L311-R311)
[[5]](diffhunk://#diff-a54ff182c7e8acf56acfd6e4b9c3ff41e2c41a31c9b211b2deb9df75d9a478f9L565-R565)

### Plugin and Widget Contributions

* Added a new "I/O Utilities" widget to `napari.yaml` for easier access
to file and export utilities from the napari interface.
[[1]](diffhunk://#diff-37781c656dd096700e29a43b6a5fb914d4e9f1632516709c538774e9fb0e5149R21-R23)
[[2]](diffhunk://#diff-37781c656dd096700e29a43b6a5fb914d4e9f1632516709c538774e9fb0e5149R72-R73)

---

These changes collectively improve maintainability, usability, and
extensibility of the codebase while introducing new features and
ensuring consistency across settings and documentation.

Author: TimMonko

.pre-commit-config.yaml

@@ -7,6 +7,8 @@ repos:
       - id: trailing-whitespace
         exclude: ^\.napari-hub/.*
       - id: check-yaml # checks for correct yaml syntax for github actions ex.
+        exclude:
+          (?x)(^src/ndevio/ndev_settings\.yaml$)
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.12.5
     hooks:
@@ -20,7 +22,7 @@ repos:
     hooks:
       - id: napari-plugin-checks
   - repo: https://github.com/ndev-kit/ndev-settings
-    rev: v0.3.0
+    rev: v0.4.0
     hooks:
       - id: reset-settings-values
   # https://mypy.readthedocs.io/en/stable/

AGENTS.md

@@ -19,7 +19,7 @@ uv venv
 .venv\Scripts\activate
 
 # Install in editable mode with testing dependencies
-uv pip install -e ".[testing]"
+uv pip install -e . --group dev
 
 # Run tests to verify setup
 pytest -v
@@ -95,7 +95,7 @@ This package is a **spiritual successor to napari-aicsimageio** but must be inde
 The reader selection follows a priority hierarchy:
 
 1. **Explicit reader parameter** - If passed directly to function
-2. **User preference from settings** - `ndev_settings.ndevio_Reader.preferred_reader`
+2. **User preference from settings** - `ndev_settings.ndevio_reader.preferred_reader`
 3. **bioio feasibility check** - Verify preferred reader supports the file
 4. **bioio auto-detection** - Fallback to bioio's plugin determination
 
@@ -282,7 +282,7 @@ ndevio/
 Settings defined in `ndev_settings.yaml`:
 
 ```yaml
-ndevio_Reader:
+ndevio_reader:
   preferred_reader:
     default: bioio-ome-tiff
     dynamic_choices:
@@ -308,7 +308,7 @@ ndevio_Reader:
 from ndev_settings import get_settings
 
 settings = get_settings()
-preferred = settings.ndevio_Reader.preferred_reader
+preferred = settings.ndevio_reader.preferred_reader
 ```
 
 ---
@@ -562,7 +562,7 @@ def get_reader(path):
 # CORRECT
 def get_preferred_reader(image, preferred_reader=None):
     settings = get_settings()
-    preferred = preferred_reader or settings.ndevio_Reader.preferred_reader
+    preferred = preferred_reader or settings.ndevio_reader.preferred_reader
 
     # Use bioio's feasibility check
     fr = bioio.plugin_feasibility_report(image)

pixi.lock

@@ -28,15 +28,20 @@ requires-python = ">=3.11"
 # or any other Qt bindings directly (e.g. PyQt5, PySide2).
 # See best practices: https://napari.org/stable/plugins/building_a_plugin/best_practices.html
 dependencies = [
-    "ndev-settings",
+    "napari",
+    "ndev-settings>=0.4.0",
+    "nbatch>=0.0.4",
+    "natsort",
+    "magicgui",
+    "magic-class",
     "xarray",
     "bioio-base",
     "bioio>=2",  # migrates writers to plugins
     "bioio-ome-zarr>=3",  # Pin to v3.x for zarr 3.x compatibility
     "bioio-ome-tiff>=1.2.0",  # minimum for migrated writer
     "bioio-tifffile",  # a backup tifffile reader with better performance than imageio
     "bioio-imageio",
-    "zarr>=3.1.3",  # Required: tifffile's ZarrTiffStore needs set_partial_values/supports_partial_writes
+    "zarr>=3.1.3",  # tifffile's ZarrTiffStore needs set_partial_values/supports_partial_writes
     "napari-plugin-manager>=0.1.7",  # Renamed to PYPI from PIP for tool selection https://github.com/napari/napari-plugin-manager/pull/176
 ]
 
@@ -52,6 +57,7 @@ dev = [
     "pytest-qt",  # https://pytest-qt.readthedocs.io/en/latest/
     "napari",
     "pyqt6",  # Explicitly use PyQt6 (napari's future default, has ARM64 macOS support)
+    "bioio-czi",  # Include an additional priority reader for development/testing
 ]
 
 [project.entry-points."napari.manifest"]
@@ -82,6 +88,9 @@ xfail_strict = true
 log_cli_level = "INFO"
 testpaths = ["tests"]
 
+[tool.coverage]
+report.fail_under = 80
+
 [tool.black]
 line-length = 79
 target-version = ['py311', 'py312', 'py313']

pyproject.toml

@@ -1,10 +1,28 @@
+from typing import TYPE_CHECKING
+
 try:  # noqa: D104
     from ._version import version as __version__
 except ImportError:
     __version__ = "unknown"
 
-from ._napari_reader import napari_get_reader
-from ._plugin_manager import ReaderPluginManager
-from .nimage import nImage
+from . import helpers
+
+# Type stub for lazy import - lets type checkers know nImage exists
+if TYPE_CHECKING:
+    from .nimage import nImage as nImage
+
+
+def __getattr__(name: str):
+    """Lazily import nImage to speed up package import."""
+    if name == "nImage":
+        from .nimage import nImage
+
+        return nImage
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
 
-__all__ = ["__version__", "nImage", "napari_get_reader", "ReaderPluginManager"]
+__all__ = [
+    "__version__",
+    "helpers",
+    "nImage",
+]

src/ndevio/__init__.py

@@ -51,13 +51,13 @@ def napari_get_reader(
     open_first_scene_only = (
         open_first_scene_only
         if open_first_scene_only is not None
-        else settings.ndevio_Reader.scene_handling == "View First Scene Only"  # type: ignore
+        else settings.ndevio_reader.scene_handling == "View First Scene Only"  # type: ignore
     ) or False
 
     open_all_scenes = (
         open_all_scenes
         if open_all_scenes is not None
-        else settings.ndevio_Reader.scene_handling == "View All Scenes"  # type: ignore
+        else settings.ndevio_reader.scene_handling == "View All Scenes"  # type: ignore
     ) or False
 
     if isinstance(path, list):
@@ -78,7 +78,7 @@ def napari_get_reader(
         # determine_reader_plugin() already enhanced the error message
         logger.error("ndevio: Unsupported file format: %s", path)
         # Show plugin installer widget if enabled in settings
-        if settings.ndevio_Reader.suggest_reader_plugins:  # type: ignore
+        if settings.ndevio_reader.suggest_reader_plugins:  # type: ignore
             _open_plugin_installer(path, e)
 
         # Return None per napari reader spec - don't raise exception