Add BatchRunner for orchestrated batch operations (#2)

This pull request introduces the new `BatchRunner` class to the `nbatch` package, providing a higher-level API for orchestrating batch operations with support for threading, progress callbacks, and cancellation. The documentation and package metadata have been updated to reflect this addition, and new optional dependencies and usage examples are included for better integration with napari and Qt-based workflows.

**Major new feature: BatchRunner integration**

- Introduced the `BatchRunner` class for orchestrating batch operations, including threading, progress/cancellation callbacks, and seamless napari integration. The API is now documented in both `README.md` and `src/nbatch/__init__.py`, and the class is exported in the package's public interface. [[1]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5R20-R24) [[2]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L184-R246) [[3]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5R332-R365) [[4]](diffhunk://#diff-b47af7882e75362ef6c3f4f6ee9347b3b112d3e049324f680ad320f40c74ed58R17-R19) [[5]](diffhunk://#diff-b47af7882e75362ef6c3f4f6ee9347b3b112d3e049324f680ad320f40c74ed58L43-R57) [[6]](diffhunk://#diff-b47af7882e75362ef6c3f4f6ee9347b3b112d3e049324f680ad320f40c74ed58R69) [[7]](diffhunk://#diff-b47af7882e75362ef6c3f4f6ee9347b3b112d3e049324f680ad320f40c74ed58R82-R83)

**Documentation and usage improvements**

- Expanded the `README.md` with recommended usage patterns for `BatchRunner`, including widget integration examples, and clarified how to use napari's `@thread_worker` directly for advanced users. [[1]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L184-R246) [[2]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5R332-R365)
- Updated the top-level docstring in `src/nbatch/__init__.py` with new examples and a description of `BatchRunner`. [[1]](diffhunk://#diff-b47af7882e75362ef6c3f4f6ee9347b3b112d3e049324f680ad320f40c74ed58R17-R19) [[2]](diffhunk://#diff-b47af7882e75362ef6c3f4f6ee9347b3b112d3e049324f680ad320f40c74ed58L43-R57)

**Dependency and packaging enhancements**

- Added optional dependencies for napari and Qt (`napari`, `pyqt6`) and grouped them under `[project.optional-dependencies]` in `pyproject.toml`, with an `all` group for convenience. Development dependencies now include these extras for full test coverage.
- Added the `Framework :: napari` classifier to better indicate napari integration.

**Minor code and typing cleanups**

- Updated type checks in `_decorator.py` and `_discovery.py` to use the `list | tuple` syntax. [[1]](diffhunk://#diff-b8b54f8f8e15eb73a90baac496cccec0e224de523851c1953a65d884abd4679dL175-R177) [[2]](diffhunk://#diff-f7448bdb0f8849649110e4176d1907acb18430dd31ea6fb0b695031a24b28cf1L190-R190)
- Clarified that the core package has no napari/Qt dependencies, only using them optionally.

Author: TimMonko

README.md

@@ -17,9 +17,11 @@ nbatch provides a foundation for batch processing operations. It's designed to w
 
 - **`@batch` decorator** - Transform single-item functions into batch-capable functions
 - **`BatchContext`** - Track progress through batch operations
+- **`BatchRunner`** - Orchestrate batch operations with threading, progress callbacks, and cancellation
 - **`discover_files()`** - Flexible file discovery with natural sorting (like file explorers)
 - **`batch_logger`** - Scoped logging for batch operations with headers/footers
 - **Minimal dependencies** - Only requires natsort for natural file ordering
+- **Optional napari integration** - Uses napari's threading when available, falls back to standard threads
 
 ## Installation
 
@@ -181,7 +183,67 @@ Batch processing completed at 2025-01-29 10:35:00
 
 ## Integration with napari
 
-nbatch is designed to work seamlessly with napari's `@thread_worker`:
+### Using BatchRunner (Recommended)
+
+`BatchRunner` provides clean orchestration for widgets with threading, progress callbacks, and cancellation:
+
+```python
+from nbatch import batch, BatchRunner
+
+# Define your processing function (pure, testable)
+@batch(on_error='continue')
+def process_image(path, model, output_dir):
+    result = model.predict(load_image(path))
+    save_result(result, output_dir / path.name)
+    return result
+
+# In your widget class
+class MyWidget:
+    def __init__(self, viewer):
+        self._viewer = viewer
+        
+        # Create runner once - reusable for all batches
+        self.runner = BatchRunner(
+            on_item_complete=self._on_item_complete,
+            on_complete=self._on_batch_complete,
+            on_error=self._on_item_error,
+            on_cancel=self._on_cancelled,
+        )
+        
+        self._run_button.clicked.connect(self.run_batch)
+        self._cancel_button.clicked.connect(self.runner.cancel)
+    
+    def _on_item_complete(self, result, ctx):
+        """Called after each item completes."""
+        self._progress_bar.setValue(ctx.index + 1)
+        # Optionally add result to viewer
+        if result is not None:
+            self._viewer.add_image(result, name=f"Result {ctx.index}")
+    
+    def _on_batch_complete(self):
+        self._progress_bar.label = "Complete!"
+    
+    def _on_item_error(self, ctx, exception):
+        self._progress_bar.label = f"Error on {ctx.item.name}"
+    
+    def _on_cancelled(self):
+        self._progress_bar.label = "Cancelled"
+    
+    def run_batch(self):
+        """Triggered by 'Run' button - just one line!"""
+        self._progress_bar.max = len(self.files)
+        self.runner.run(
+            process_image,
+            self.files,
+            model=self.model,
+            output_dir=self.output_dir,
+            log_file=self.output_dir / "batch.log",
+        )
+```
+
+### Using @thread_worker directly
+
+For more control, use napari's `@thread_worker` with the `@batch` decorator:
 
 ```python
 from napari.qt.threading import thread_worker
@@ -267,6 +329,40 @@ def batch_logger(
 ) -> Generator[BatchLogger, None, None]: ...
 ```
 
+### `BatchRunner`
+
+```python
+class BatchRunner:
+    def __init__(
+        self,
+        on_item_complete: Callable[[Any, BatchContext], None] | None = None,
+        on_complete: Callable[[], None] | None = None,
+        on_error: Callable[[BatchContext, Exception], None] | None = None,
+        on_cancel: Callable[[], None] | None = None,
+    ): ...
+    
+    def run(
+        self,
+        func: Callable,
+        items: Any,
+        *args,
+        threaded: bool = True,
+        log_file: str | Path | None = None,
+        log_header: Mapping[str, object] | None = None,
+        patterns: str | Sequence[str] = '*',
+        recursive: bool = False,
+        **kwargs,
+    ) -> None: ...
+    
+    def cancel(self) -> None: ...
+    
+    @property
+    def is_running(self) -> bool: ...
+    
+    @property
+    def was_cancelled(self) -> bool: ...
+```
+
 ## Contributing
 
 Contributions are welcome! Please ensure tests pass before submitting a pull request:

pyproject.toml

@@ -11,6 +11,7 @@ authors = [
 ]
 classifiers = [
     "Development Status :: 2 - Pre-Alpha",
+    "Framework :: napari",
     "Intended Audience :: Developers",
     "Operating System :: OS Independent",
     "Programming Language :: Python",
@@ -31,11 +32,25 @@ dependencies = [
     "natsort",
 ]
 
+[project.optional-dependencies]
+napari = [
+    "napari",
+]
+qtpy-backend = [
+    "pyqt6",
+]
+all = [
+    "nbatch[napari]",
+    "nbatch[qtpy-backed]",
+]
+
 [dependency-groups]
 dev = [
     "tox-uv",
     "pytest",  # https://docs.pytest.org/en/latest/contents.html
     "pytest-cov",  # https://pytest-cov.readthedocs.io/en/latest/
+    "pytest-qt",  # Qt testing utilities (qtbot fixture)
+    "napari[pyqt6]",  # Include napari and Qt for full test coverage
 ]
 
 [project.entry-points."napari.manifest"]

src/nbatch/__init__.py

@@ -2,7 +2,7 @@
 
 This package provides a lightweight foundation for batch
 processing operations. It's designed to work with napari plugins but has
-no napari or Qt dependencies itself.
+no napari or Qt dependencies in the core modules.
 
 Core Components
 ---------------
@@ -14,6 +14,9 @@
     Discover files from paths, directories, or iterables.
 batch_logger : context manager
     Scoped logging for batch operations with optional file output.
+BatchRunner : class
+    Orchestrates batch operations with threading, progress, and cancellation.
+    Uses napari's threading when available, falls back to standard threads.
 
 Examples
 --------
@@ -40,8 +43,18 @@
 
 >>> from nbatch import batch_logger
 >>> with batch_logger(log_file="output/log.txt", header={"Files": 100}) as log:
-...     for result, ctx in process(files, with_context=True):
+...     for result, ctx in process(files):
 ...         log(ctx, f"Processed: {result}")
+
+With BatchRunner (for widgets):
+
+>>> from nbatch import BatchRunner
+>>> runner = BatchRunner(
+...     on_item_complete=lambda result, ctx: progress_bar.setValue(ctx.index + 1),
+...     on_complete=lambda: print("Done!"),
+... )
+>>> runner.run(process, files)  # Threaded, non-blocking
+>>> runner.cancel()  # Cancel if needed
 """
 
 try:
@@ -53,6 +66,7 @@
 from nbatch._decorator import batch
 from nbatch._discovery import discover_files, is_batch_input
 from nbatch._logging import BatchLogger, batch_logger
+from nbatch._runner import BatchRunner
 
 __all__ = [
     # Core decorator
@@ -65,4 +79,6 @@
     # Logging
     'batch_logger',
     'BatchLogger',
+    # Runner
+    'BatchRunner',
 ]

src/nbatch/_decorator.py

@@ -172,9 +172,9 @@ def wrapper(
                 items = discover_files(
                     first_arg, patterns=patterns, recursive=recursive
                 )
-            elif isinstance(first_arg, (list, tuple)):
+            elif isinstance(first_arg, list | tuple):
                 # Could be paths or other items
-                if first_arg and isinstance(first_arg[0], (str, Path)):
+                if first_arg and isinstance(first_arg[0], str | Path):
                     items = discover_files(first_arg)
                 else:
                     items = list(first_arg)

src/nbatch/_discovery.py

@@ -187,6 +187,6 @@ def is_batch_input(item: object) -> bool:
     >>> is_batch_input("single.tif")
     False
     """
-    if isinstance(item, (list, tuple)):
+    if isinstance(item, list | tuple):
         return True
     return isinstance(item, Path) and item.is_dir()