Merge pull request #119 from ArcanaFramework/comprehensive-mime-like

Optional loading of extras dependencies

Author: tclose

README.md

@@ -37,7 +37,9 @@ extensions and magic numbers. As such, many of the formats in the library have n
 tested on real data and so should be treated with some caution. If you encounter any issues with an implemented file
 type, please raise an issue in the [GitHub tracker](https://github.com/ArcanaFramework/fileformats/issues).
 
-Adding support for vendor formats is planned for v1.0.
+A small selection of vendor-specific types can be found under `fileformats.vendor.*`. Support for additional vendor-specific
+formats can be added via plugin (see the
+[extension template](https://github.com/ArcanaFramework/fileformats-extension-template)).
 
 ## Installation
 

extras/fileformats/extras/application/medical.py

@@ -1,12 +1,20 @@
 import sys
 import typing as ty
 from pathlib import Path
-import pydicom.tag
 from fileformats.core import FileSet, extra_implementation
+from fileformats.extras.core import check_optional_dependency
 from fileformats.application import Dicom
-import medimages4tests.dummy.dicom.mri.t1w.siemens.skyra.syngo_d13c
 from fileformats.core import SampleFileGenerator
 
+try:
+    import pydicom.tag
+except ImportError:
+    pydicom = None  # type: ignore[assignment]
+try:
+    import medimages4tests.dummy.dicom.mri.t1w.siemens.skyra.syngo_d13c
+except ImportError:
+    medimages4tests = None  # type: ignore[assignment]
+
 if sys.version_info <= (3, 11):
     from typing_extensions import TypeAlias
 else:
@@ -16,7 +24,7 @@
     ty.List[int],
     ty.List[str],
     ty.List[ty.Tuple[int, int]],
-    ty.List[pydicom.tag.BaseTag],
+    ty.List["pydicom.tag.BaseTag"],
 ]
 
 
@@ -26,6 +34,7 @@ def dicom_read_metadata(
     metadata_keys: ty.Optional[TagListType] = None,
     **kwargs: ty.Any,
 ) -> ty.Mapping[str, ty.Any]:
+    check_optional_dependency(pydicom)
     dcm = pydicom.dcmread(
         dicom.fspath, specific_tags=metadata_keys, stop_before_pixels=True
     )
@@ -37,6 +46,7 @@ def dicom_generate_sample_data(
     dicom: Dicom,
     generator: SampleFileGenerator,
 ) -> ty.List[Path]:
+    check_optional_dependency(medimages4tests)
     return next(
         medimages4tests.dummy.dicom.mri.t1w.siemens.skyra.syngo_d13c.get_image(
             out_dir=generator.dest_dir
@@ -49,15 +59,17 @@ def dicom_load(
     dicom: Dicom,
     specific_tags: ty.Optional[TagListType] = None,
     **kwargs: ty.Any,
-) -> pydicom.FileDataset:
+) -> "pydicom.FileDataset":
+    check_optional_dependency(pydicom)
     return pydicom.dcmread(dicom.fspath, specific_tags=specific_tags)
 
 
 @extra_implementation(FileSet.save)
 def dicom_save(
     dicom: Dicom,
-    data: pydicom.FileDataset,
+    data: "pydicom.FileDataset",
     write_like_original: bool = False,
     **kwargs: ty.Any,
 ) -> None:
+    check_optional_dependency(pydicom)
     pydicom.dcmwrite(dicom.fspath, data, write_like_original=write_like_original)

extras/fileformats/extras/core/__init__.py

@@ -1,3 +1,24 @@
 """Only required to hold the automatically generated version for the "core" extras"""
 
+import typing as ty
+import types
+import inspect
 from ._version import __version__
+
+
+def check_optional_dependency(module: ty.Optional[types.ModuleType]) -> None:
+    if module is None:
+        frame = inspect.currentframe()
+        while frame:
+            # Find the frame where the decorated_extra method was called
+            if frame.f_code.co_name == "decorated_extra":
+                extras_module = frame.f_locals["extras"][0].pkg.split(".")[-1]
+                break
+            frame = frame.f_back
+        raise ImportError(
+            f"The optional dependencies are not installed for '{extras_module}', please include when "
+            f"installing fileformats-extras, e.g. `pip install 'fileformats-extras[{extras_module}]'`"
+        )
+
+
+__all__ = ["__version__"]

extras/fileformats/extras/core/tests/test_import_check.py

@@ -0,0 +1,10 @@
+from fileformats.testing import MyFormat
+import pytest
+
+
+def test_check_optional_dependency_fail():
+
+    with pytest.raises(
+        ImportError, match="The optional dependencies are not installed for 'testing'"
+    ):
+        MyFormat.sample().dummy_extra()

extras/fileformats/extras/image/readwrite.py

@@ -1,18 +1,29 @@
-import imageio
 import typing as ty
-import numpy  # noqa: F401
-import typing  # noqa: F401
+
+
+# import numpy  # noqa: F401
+# import typing  # noqa: F401
+from fileformats.extras.core import check_optional_dependency
 from fileformats.core import FileSet, extra_implementation
 from fileformats.image.raster import RasterImage, DataArrayType
 
+try:
+    import imageio  # noqa: F401
+except ImportError:
+    imageio = None  # type: ignore
+
 
 @extra_implementation(FileSet.load)
 def read_raster_data(image: RasterImage, **kwargs: ty.Any) -> DataArrayType:
+    check_optional_dependency(imageio)
+
     return imageio.imread(image.fspath)  # type: ignore
 
 
 @extra_implementation(FileSet.save)
 def write_raster_data(
     image: RasterImage, data: DataArrayType, **kwargs: ty.Any
 ) -> None:
+    check_optional_dependency(imageio)
+
     imageio.imwrite(image.fspath, data, **kwargs)

extras/fileformats/extras/image/tests/test_image_converters.py

@@ -1,17 +1,16 @@
-# import sys
 import pytest
-from imageio.core.fetching import get_remote_file
 from fileformats.image import Bitmap, Gif, Jpeg, Png, Tiff
+from imageio.core.fetching import get_remote_file
 
 
 @pytest.fixture(scope="session")
 def jpg() -> Jpeg:
-    # imageio.imread("imageio:bricks.jpg")
     return Jpeg(get_remote_file("images/bricks.jpg"))
 
 
 @pytest.fixture(scope="session")
 def png() -> Png:
+
     return Png(get_remote_file("images/chelsea.png"))
 
 

extras/fileformats/extras/testing/__init__.py

@@ -1,9 +1,12 @@
 from pydra.compose import python
 
-from fileformats.core import converter
-from fileformats.testing import AbstractFile, ConvertibleToFile, EncodedText
+from fileformats.core import converter, extra_implementation
+from fileformats.extras.core import check_optional_dependency
+from fileformats.testing import AbstractFile, ConvertibleToFile, EncodedText, MyFormat
 from fileformats.text import TextFile
 
+dummy_import = None
+
 
 @converter  # pyright: ignore[reportArgumentType]
 @python.define(outputs=["out_file"])  # type: ignore[misc]
@@ -31,3 +34,9 @@ def EncodedToTextConverter(in_file: EncodedText) -> TextFile:
     out_file = TextFile.sample()
     out_file.write_text(decoded_contents)
     return out_file
+
+
+@extra_implementation(MyFormat.dummy_extra)
+def my_format_dummy_extra(my_format: MyFormat) -> int:
+    check_optional_dependency(dummy_import)
+    return 42

extras/fileformats/extras/vendor/openxmlformats_officedocument/application.py

@@ -1,19 +1,26 @@
 import typing as ty
 
-from docx import Document
-from docx.document import Document as DocumentObject
+try:
+    import docx.document
+except ImportError:
+    docx = None  # type: ignore[assignment]
 
 from fileformats.core import FileSet, extra_implementation
+from fileformats.extras.core import check_optional_dependency
 from fileformats.vendor.openxmlformats_officedocument.application import (
     Wordprocessingml_Document as MswordX,
 )
 
 
 @extra_implementation(FileSet.load)
-def load_docx(doc: MswordX, **kwargs: ty.Any) -> DocumentObject:
-    return Document(str(doc))  # type: ignore[no-any-return]
+def load_docx(doc: MswordX, **kwargs: ty.Any) -> "docx.document.Document":
+    check_optional_dependency(docx)
+    return docx.Document(str(doc))  # type: ignore[no-any-return]
 
 
 @extra_implementation(FileSet.save)
-def save_docx(doc: MswordX, data: DocumentObject, **kwargs: ty.Any) -> None:
+def save_docx(doc: MswordX, data: "docx.document.Document", **kwargs: ty.Any) -> None:
+    check_optional_dependency(docx)
+    if not isinstance(data, docx.document.Document):
+        raise TypeError(f"Expected a 'docx.document.Document' object, got {type(data)}")
     data.save(str(doc))

extras/pyproject.toml

@@ -37,7 +37,6 @@ test = [
     "pytest-env>=0.6.2",
     "pytest-cov>=2.12.1",
     "codecov",
-    "medimages4tests",
 ]
 application = [
     "PyYAML>=6.0",

fileformats/core/extras.py

@@ -34,7 +34,7 @@ def extra(method: ExtraMethod) -> "ExtraMethod":
     dispatch_method: ty.Callable[..., ty.Any] = functools.singledispatch(method)
 
     @functools.wraps(method)
-    def decorated(obj: DataType, *args: ty.Any, **kwargs: ty.Any) -> ty.Any:
+    def decorated_extra(obj: DataType, *args: ty.Any, **kwargs: ty.Any) -> ty.Any:
         cls = type(obj)
         extras = []
         for tp in cls.referenced_types():  # type: ignore[attr-defined]
@@ -61,8 +61,8 @@ def decorated(obj: DataType, *args: ty.Any, **kwargs: ty.Any) -> ty.Any:
 
     # Store single dispatch method on the decorated function so we can register
     # implementations to it later
-    decorated._dispatch = dispatch_method  # type: ignore[attr-defined]
-    return decorated  # type: ignore[return-value]
+    decorated_extra._dispatch = dispatch_method  # type: ignore[attr-defined]
+    return decorated_extra  # type: ignore[return-value]
 
 
 def extra_implementation(
@@ -78,7 +78,9 @@ def extra_implementation(
             "an implementation"
         )
 
-    def decorator(implementation: ExtraImplementation) -> ExtraImplementation:
+    def extra_implementation_decorator(
+        implementation: ExtraImplementation,
+    ) -> ExtraImplementation:
         msig = inspect.signature(method)
         fsig = inspect.signature(implementation)
         msig_args = list(msig.parameters.values())[1:]
@@ -188,7 +190,7 @@ def type_match(mtype: ty.Union[str, type], ftype: ty.Union[str, type]) -> bool:
         dispatch_method.register(implementation)
         return implementation
 
-    return decorator
+    return extra_implementation_decorator
 
 
 WrappedTask = ty.TypeVar("WrappedTask", bound=ty.Callable[..., ty.Any])