Merge pull request #126 from bioio-devs/feature/migrate-writers

feature/migrate-writers

Author: BrianWhitneyAI

README.md

@@ -71,5 +71,30 @@ this registry.
 
 Each reader plugin should closely follow the specification laid out in `bioio-base`. As such, it is likely common that reader plugins won't distribute their own documentation and users should instead review  [`bioio_base.reader.Reader`](https://bioio-devs.github.io/bioio-base/bioio_base.html#bioio_base.reader.Reader) for API documentation for the underlying Reader API. We encourage plugin authors to publish their own documentation if they change or include new features into their published image readers.
 
+## Writer Registry
+
+BioIO supports a set of writer backends for exporting image data. The writer registry below lists maintained writer plug-ins.
+
+| Writer           | Extension                                              | Documentation |
+| ---------------- | ------------------------------------------------------ | ------------- |
+| OmeTiffWriter    | .ome.tiff                                              | [Repo](https://github.com/bioio-devs/bioio-ome-tiff)          |
+| OmeZarrWriterV2  | .ome.zarr (OME 0.4.0, Zarr 2)                           | [Repo](https://github.com/bioio-devs/bioio-ome-zarr)          |
+| OmeZarrWriterV3  | .ome.zarr (OME 0.5.0, Zarr 3)                           | [Repo](https://github.com/bioio-devs/bioio-ome-zarr)          |
+| TimeSeriesWriter | .gif, .mp4, .mkv                                       | [Repo](https://github.com/bioio-devs/bioio-imageio)          |
+| TwoDWriter       | .png, .bmp, .jpg, .mov, .avi, .mpg, .mpeg, .mp4, .mkv, .wmv, .ogg | [Repo](https://github.com/bioio-devs/bioio-imageio)          |
+
+
+### Writer Installation and Usage
+Writers will be installed with the respective plugin. Once installed they can be imported via `bioio.writers`.
+ex. `bioio.writers<Writer Name>`
+
+```python
+import numpy as np
+from bioio.writers import OmeTiffWriter # with bioio-ome-tiff installed
+
+image = np.random.rand(10, 3, 1024, 2048)
+OmeTiffWriter.save(image, "file.ome.tiff", dim_order="ZCYX")
+```
+
 ## Issues
 [_Click here to view all open issues in bioio-devs organization at once_](https://github.com/search?q=user%3Abioio-devs+is%3Aissue+is%3Aopen&type=issues&ref=advsearch)

bioio/__init__.py

@@ -1,4 +1,4 @@
-# -*- coding: utf-8 -*-
+#!/usr/bin/env python
 
 """Top-level package for bioio."""
 

bioio/bio_image.py

@@ -1134,6 +1134,7 @@ def save(
     ) -> None:
         """
         Saves the file data to OME-TIFF format with general naive best practices.
+        (Requires bioio-ome-tiff plugin installed)
 
         Parameters
         ----------
@@ -1146,17 +1147,27 @@ def save(
 
         Notes
         -----
-        See `bioio.writers.OmeTiffWriter` for more in-depth specification
-        and the `bioio.writers` module as a whole for list of all available
-        file writers.
+        See `bioio_ome_tiff.writers.OmeTiffWriter` for more in-depth specification
+        and the bioio writer registry in the README module as a whole for list of
+        all available file writers.
 
         When reading in the produced OME-TIFF file, scenes IDs may have changed.
         This is due to how certain file and metadata formats do or do-not have IDs
         and simply names. In converting to OME-TIFF we will always store the scene
         ids in each Image's name attribute but IDs will be generated. The order of the
         scenes will be the same (or whatever order was specified / provided).
         """
-        from .writers import OmeTiffWriter
+        import bioio.writers as _writers  # type: ignore[attr-defined]
+
+        OmeTiffWriter = getattr(_writers, "OmeTiffWriter", None)
+
+        if OmeTiffWriter is None:
+            log.warning(
+                "TIFF writing support (OmeTiffWriter) is not available. "
+                "To enable it, install the plugin:\n"
+                "    pip install bioio-ome-tiff"
+            )
+            return
 
         # Get all parameters as dict of lists, or static because of unchanging values
         datas: List[biob.types.ArrayLike] = []

bioio/tests/__init__.py

@@ -1,3 +1,3 @@
-# -*- coding: utf-8 -*-
+#!/usr/bin/env python
 
 """Unit test package for bioio."""

bioio/tests/dummy-plugin/dummy_plugin/writer.py

@@ -0,0 +1,22 @@
+from typing import Any
+
+import bioio_base as biob
+from bioio_base.writer import Writer
+
+
+class DummyWriter(Writer):
+    """
+    A dummy writer for testing bioio.writers entry-point discovery.
+    """
+
+    @staticmethod
+    def save(
+        data: biob.types.ArrayLike,
+        uri: biob.types.PathLike,
+        dim_order: str = biob.dimensions.DEFAULT_DIMENSION_ORDER,
+        **kwargs: Any,
+    ) -> None:
+        """
+        Stub implementation that deliberately isn’t implemented.
+        """
+        raise NotImplementedError("DummyWriter.save is a stub")

bioio/tests/dummy-plugin/pyproject.toml

@@ -47,6 +47,9 @@ test = [
 [project.entry-points."bioio.readers"]
 dummy-plugin = "dummy_plugin"
 
+[project.entry-points."bioio.writers"]
+DummyWriter = "dummy_plugin.writer:DummyWriter"
+
 # build settings
 # https://setuptools.pypa.io/en/latest/userguide/pyproject_config.html
 [tool.setuptools]

bioio/tests/test_bio_image.py

@@ -2,12 +2,7 @@
 # -*- coding: utf-8 -*-
 
 import pathlib
-import sys
-
-if sys.version_info < (3, 10):
-    from importlib_metadata import EntryPoint
-else:
-    from importlib.metadata import EntryPoint
+from importlib.metadata import EntryPoint
 
 import bioio_base as biob
 import numpy as np

bioio/tests/test_writer.py

@@ -0,0 +1,28 @@
+from importlib.metadata import entry_points
+
+import pytest
+
+
+def test_dummy_writer_discovery_and_api(dummy_plugin: str) -> None:
+    # Entry-point registration
+    eps = entry_points(group="bioio.writers")
+    names = {ep.name for ep in eps}
+    assert "DummyWriter" in names, f"found: {sorted(names)}"
+
+    # Public API (__all__)
+    import bioio.writers as pkg
+
+    assert "DummyWriter" in getattr(pkg, "__all__", [])
+
+    # Import works (dynamic, so ignore mypy attr-defined error)
+    from bioio.writers import DummyWriter  # type: ignore[attr-defined]
+
+    assert DummyWriter.__name__ == "DummyWriter"
+
+
+def test_dummy_writer_save_stub(dummy_plugin: str) -> None:
+    # The save() stub should raise NotImplementedError
+    from bioio.writers import DummyWriter  # type: ignore[attr-defined]
+
+    with pytest.raises(NotImplementedError):
+        DummyWriter.save(data=[1], uri="unused", dim_order="XYZ")