ReaderChain and image reader

14 files changed, 492 insertions, 2 deletions

diff --git a/.gitignore b/.gitignore
index e45b114..8e1df10 100644
--- a/.gitignore
+++ b/.gitignore
@@ -22,4 +22,7 @@ build/
 # doc builds
 doc/build/
 
+# testing data
+test/reader/image/testimage.nef
+
 ## EOF ##
diff --git a/bsie/reader/base.py b/bsie/reader/base.py
index 08d6cc6..099a327 100644
--- a/bsie/reader/base.py
+++ b/bsie/reader/base.py
@@ -39,7 +39,7 @@ class Reader(abc.ABC):
         return hash(type(self))
 
     @abc.abstractmethod
-    def __call__(self, path: bsfs.URI) -> typing.Any:
+    def __call__(self, path: str) -> typing.Any:
         """Return some content of the file at *path*.
         Raises a `ReaderError` if the reader cannot make sense of the file format.
         """
diff --git a/bsie/reader/chain.py b/bsie/reader/chain.py
new file mode 100644
index 0000000..8e900e1
--- /dev/null
+++ b/bsie/reader/chain.py
@@ -0,0 +1,85 @@
+"""
+
+Part of the bsie module.
+A copy of the license is provided with the project.
+Author: Matthias Baumgartner, 2022
+"""
+# standard imports
+import logging
+import typing
+
+# bsie imports
+from bsie.utils import bsfs, errors
+
+# inner-module imports
+from . import base
+from . import builder
+
+# exports
+__all__: typing.Sequence[str] = (
+    'ReaderChain',
+    )
+
+
+## code ##
+
+logger = logging.getLogger(__name__)
+
+# Content type.
+T_CONTENT = typing.TypeVar('T_CONTENT') # pylint: disable=invalid-name
+
+class ReaderChain(base.Reader, typing.Generic[T_CONTENT]):
+    """Read an image."""
+
+    # sub-readers for specific file formats.
+    _children: typing.Tuple[base.Reader, ...]
+
+    def __init__(
+            self,
+            subreader_names: typing.Iterable[str],
+            cfg: typing.Any,
+            ):
+        rbuild = builder.ReaderBuilder(cfg)
+        children = []
+        for name in subreader_names:
+            try:
+                # build sub-reader
+                children.append(rbuild.build(name))
+            except (ValueError,
+                    TypeError,
+                    errors.LoaderError,
+                    errors.BuilderError) as err:
+                # failed to build a child; skip and notify
+                logger.warning('failed to load reader: %s', err)
+
+        if len(children) == 0:
+            logger.warning('%s failed to load any sub-readers.', bsfs.typename(self))
+
+        # copy children to member
+        self._children = tuple(children)
+
+    def __str__(self) -> str:
+        substr = ', '.join(str(child) for child in self._children)
+        return f'{bsfs.typename(self)}({substr})'
+
+    def __repr__(self) -> str:
+        return f'{bsfs.typename(self)}({self._children})'
+
+    def __eq__(self, other: typing.Any) -> bool:
+        return super().__eq__(other) \
+           and self._children == other._children
+
+    def __hash__(self) -> int:
+        return hash((super().__hash__(), self._children))
+
+    def __call__(self, path: str) -> T_CONTENT:
+        for child in self._children:
+            try:
+                return child(path)
+            except errors.ReaderError:
+                # child cannot read the file, skip.
+                pass
+
+        raise errors.ReaderError(path)
+
+## EOF ##
diff --git a/bsie/reader/image/__init__.py b/bsie/reader/image/__init__.py
new file mode 100644
index 0000000..85dad85
--- /dev/null
+++ b/bsie/reader/image/__init__.py
@@ -0,0 +1,36 @@
+"""
+
+Part of the bsie module.
+A copy of the license is provided with the project.
+Author: Matthias Baumgartner, 2022
+"""
+# standard imports
+import typing
+
+# external imports
+import PIL.Image
+
+# inner-module imports
+from .. import chain
+
+# constants
+_FILE_FORMAT_READERS: typing.Sequence[str] = (
+    __package__ + '._raw.RawImage',
+    __package__ + '._pillow.PillowImage',
+    )
+
+# exports
+__all__: typing.Sequence[str] = (
+    'Image',
+    )
+
+
+## code ##
+
+class Image(chain.ReaderChain[PIL.Image]): # pylint: disable=too-few-public-methods
+    """Read an image file."""
+
+    def __init__(self, cfg):
+        super().__init__(_FILE_FORMAT_READERS, cfg)
+
+## EOF ##
diff --git a/bsie/reader/image/_pillow.py b/bsie/reader/image/_pillow.py
new file mode 100644
index 0000000..ee0662d
--- /dev/null
+++ b/bsie/reader/image/_pillow.py
@@ -0,0 +1,37 @@
+"""
+
+Part of the bsie module.
+A copy of the license is provided with the project.
+Author: Matthias Baumgartner, 2022
+"""
+# standard imports
+import typing
+
+# external imports
+import PIL.Image
+
+# bsie imports
+from bsie.utils import errors
+
+# inner-module imports
+from .. import base
+
+# exports
+__all__: typing.Sequence[str] = (
+    'PillowImage',
+    )
+
+
+## code ##
+
+class PillowImage(base.Reader):
+    """Use PIL to read content of a variety of image file types."""
+
+    def __call__(self, path: str) -> PIL.Image:
+        try:
+            # open file with PIL
+            return PIL.Image.open(path)
+        except IOError as err:
+            raise errors.ReaderError(path) from err
+
+# EOF ##
diff --git a/bsie/reader/image/_raw.py b/bsie/reader/image/_raw.py
new file mode 100644
index 0000000..77be357
--- /dev/null
+++ b/bsie/reader/image/_raw.py
@@ -0,0 +1,61 @@
+"""
+
+Part of the bsie module.
+A copy of the license is provided with the project.
+Author: Matthias Baumgartner, 2022
+"""
+# standard imports
+import typing
+
+# external imports
+import PIL.Image
+import rawpy
+
+# bsie imports
+from bsie.utils import errors, filematcher
+
+# inner-module imports
+from .. import base
+
+# constants
+MATCH_RULE = 'mime={image/x-nikon-nef} | extension={nef}'
+
+# exports
+__all__: typing.Sequence[str] = (
+    'RawImage',
+    )
+
+
+## code ##
+
+class RawImage(base.Reader):
+    """Use rawpy to read content of raw image file types."""
+
+    # file matcher
+    match: filematcher.Matcher
+
+    # additional kwargs to rawpy's postprocess
+    rawpy_kwargs: typing.Dict[str, typing.Any]
+
+    def __init__(self, **rawpy_kwargs):
+        match_rule = rawpy_kwargs.pop('file_match_rule', MATCH_RULE)
+        self._match = filematcher.parse(match_rule)
+        self._rawpy_kwargs = rawpy_kwargs
+
+    def __call__(self, path: str) -> PIL.Image:
+        # perform quick checks first
+        if not self._match(path):
+            raise errors.ReaderError(path)
+
+        try:
+            # open file with rawpy
+            ary = rawpy.imread(path).postprocess(**self._rawpy_kwargs)
+            # convert to PIL.Image
+            return PIL.Image.fromarray(ary)
+        except (rawpy.LibRawFatalError, # pylint: disable=no-member # pylint doesn't find the errors
+                rawpy.NotSupportedError, # pylint: disable=no-member
+                rawpy.LibRawNonFatalError, # pylint: disable=no-member
+               ) as err:
+            raise errors.ReaderError(path) from err
+
+## EOF ##
diff --git a/setup.py b/setup.py
index 6521593..2f7a485 100644
--- a/setup.py
+++ b/setup.py
@@ -14,7 +14,17 @@ setup(
     url='https://www.igsor.net/projects/blackstar/bsie/',
     download_url='https://pip.igsor.net',
     packages=('bsie', ),
-    install_requires=('rdflib', 'bsfs', 'python-magic', 'pyparsing'),
+    install_requires=(
+        'bsfs',
+        'pyparsing',
+        'python-magic',
+        'rdflib', # only for tests
+        'requests', # only for tests
+        ),
     python_requires=">=3.7",
+    extra_require=(
+        # image reader
+        'pillow', 'rawpy',
+        )
 )
 
diff --git a/test/reader/image/__init__.py b/test/reader/image/__init__.py
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/test/reader/image/__init__.py
diff --git a/test/reader/image/load_nef.py b/test/reader/image/load_nef.py
new file mode 100644
index 0000000..5ba0adc
--- /dev/null
+++ b/test/reader/image/load_nef.py
@@ -0,0 +1,28 @@
+"""
+
+Part of the bsie test suite.
+A copy of the license is provided with the project.
+Author: Matthias Baumgartner, 2022
+"""
+# standard imports
+import os
+
+# external imports
+import requests
+
+# constants
+IMAGE_URL = 'http://igsor.net/eik7AhvohghaeN5.nef'
+
+## code ##
+
+def get():
+    """Download a raw test image."""
+    target = os.path.join(os.path.dirname(__file__), 'testimage.nef')
+    if not os.path.exists(target):
+        with open(target, 'wb') as ofile:
+            ans = requests.get(IMAGE_URL)
+            ofile.write(ans.content)
+
+
+
+## EOF ##
diff --git a/test/reader/image/test_image.py b/test/reader/image/test_image.py
new file mode 100644
index 0000000..c60ca75
--- /dev/null
+++ b/test/reader/image/test_image.py
@@ -0,0 +1,51 @@
+"""
+
+Part of the bsie test suite.
+A copy of the license is provided with the project.
+Author: Matthias Baumgartner, 2022
+"""
+# standard imports
+import importlib
+import os
+import unittest
+
+# bsie imports
+from bsie.utils import errors
+
+# objects to test
+from bsie.reader.image import Image
+
+
+## code ##
+
+class TestImage(unittest.TestCase):
+    def setUp(self):
+        importlib.import_module(__package__ + '.load_nef').get()
+
+    def test_construct(self):
+        image = Image({})
+        self.assertIsInstance(image, Image)
+        self.assertEqual(len(image._children), 2)
+
+    def test_call(self):
+        image = Image({})
+        # call returns raw image
+        img = image(os.path.join(os.path.dirname(__file__), 'testimage.nef'))
+        self.assertEqual(img.size, (6016, 4016)) # FIXME: change when image was replaced
+        img.close()
+        # call returns jpeg image
+        img = image(os.path.join(os.path.dirname(__file__), 'testimage.jpg'))
+        self.assertEqual(img.size, (1, 1))
+        img.close()
+        # call raises error if file cannot be read
+        self.assertRaises(errors.ReaderError, image,
+            os.path.join(os.path.dirname(__file__), 'invalid.nef'))
+        self.assertRaises(errors.ReaderError, image,
+            os.path.join(os.path.dirname(__file__), 'invalid.jpg'))
+
+## main ##
+
+if __name__ == '__main__':
+    unittest.main()
+
+## EOF ##
diff --git a/test/reader/image/test_pillow.py b/test/reader/image/test_pillow.py
new file mode 100644
index 0000000..8abf5c1
--- /dev/null
+++ b/test/reader/image/test_pillow.py
@@ -0,0 +1,44 @@
+"""
+
+Part of the bsie test suite.
+A copy of the license is provided with the project.
+Author: Matthias Baumgartner, 2022
+"""
+# standard imports
+import os
+import unittest
+
+# external imports
+import PIL.Image
+
+# bsie imports
+from bsie.utils import errors
+
+# objects to test
+from bsie.reader.image._pillow import PillowImage
+
+
+## code ##
+
+class TestPillowImage(unittest.TestCase):
+    def test_call(self):
+        rdr = PillowImage()
+        # returns PIL image
+        img = rdr(os.path.join(os.path.dirname(__file__), 'testimage.jpg'))
+        self.assertEqual(img.size, (1, 1))
+        self.assertEqual(img.getdata().getpixel((0, 0)), (0, 0, 0))
+        img.close()
+        # raises exception when image cannot be read
+        self.assertRaises(errors.ReaderError, rdr,
+            os.path.join(os.path.dirname(__file__), 'invalid.jpg'))
+        # NOTE: PIL can actually read raw image files (returns the thumbnail)
+        #self.assertRaises(errors.ReaderError, rdr,
+        #    os.path.join(os.path.dirname(__file__), 'testimage.nef'))
+
+
+## main ##
+
+if __name__ == '__main__':
+    unittest.main()
+
+## EOF ##
diff --git a/test/reader/image/test_raw_image.py b/test/reader/image/test_raw_image.py
new file mode 100644
index 0000000..3d5f887
--- /dev/null
+++ b/test/reader/image/test_raw_image.py
@@ -0,0 +1,50 @@
+"""
+
+Part of the bsie test suite.
+A copy of the license is provided with the project.
+Author: Matthias Baumgartner, 2022
+"""
+# standard imports
+import importlib
+import os
+import unittest
+
+# external imports
+import PIL.Image
+
+# bsie imports
+from bsie.utils import errors
+
+# objects to test
+from bsie.reader.image._raw import RawImage
+
+
+## code ##
+
+class TestRawImage(unittest.TestCase):
+    def setUp(self):
+        importlib.import_module(__package__ + '.load_nef').get()
+
+    def test_call(self):
+        rdr = RawImage()
+        # returns PIL image
+        img = rdr(os.path.join(os.path.dirname(__file__), 'testimage.nef'))
+        self.assertEqual(img.size, (6016, 4016)) # FIXME: change when image was replaced
+        #self.assertEqual(img.size, (1, 1))
+        #self.assertEqual(img.getdata().getpixel((0, 0)), (0, 0, 0))
+        img.close()
+        # raises exception when image cannot be read
+        self.assertRaises(errors.ReaderError, rdr,
+            os.path.join(os.path.dirname(__file__), 'invalid.nef'))
+        self.assertRaises(errors.ReaderError, rdr,
+            os.path.join(os.path.dirname(__file__), 'testimage.jpg'))
+
+
+
+
+## main ##
+
+if __name__ == '__main__':
+    unittest.main()
+
+## EOF ##
diff --git a/test/reader/image/testimage.jpg b/test/reader/image/testimage.jpg
new file mode 100644
index 0000000..ea7af63
--- /dev/null
+++ b/test/reader/image/testimage.jpg
diff --git a/test/reader/test_chain.py b/test/reader/test_chain.py
new file mode 100644
index 0000000..901faa1
--- /dev/null
+++ b/test/reader/test_chain.py
@@ -0,0 +1,85 @@
+"""
+
+Part of the bsie test suite.
+A copy of the license is provided with the project.
+Author: Matthias Baumgartner, 2022
+"""
+# standard imports
+import logging
+import os
+import unittest
+
+# bsie imports
+from bsie.utils import errors
+import bsie.reader.path
+import bsie.reader.stat
+
+# objects to test
+from bsie.reader.chain import ReaderChain
+
+
+## code ##
+
+class TestReaderChain(unittest.TestCase):
+    def test_construct(self):
+        # subreaders are built
+        chain = ReaderChain(['bsie.reader.stat.Stat', 'bsie.reader.path.Path'], {})
+        self.assertIsInstance(chain, ReaderChain)
+        self.assertEqual(chain._children,
+            (bsie.reader.stat.Stat(), bsie.reader.path.Path()))
+        # subreaders that failed to build are omitted
+        with self.assertLogs(logging.getLogger('bsie.reader.chain'), logging.WARNING):
+            chain = ReaderChain(['bsie.reader.stat.Stat', 'bsie.reader.invalid.Invalid'], {})
+            self.assertEqual(chain._children, (bsie.reader.stat.Stat(), ))
+        with self.assertLogs(logging.getLogger('bsie.reader.chain'), logging.WARNING):
+            chain = ReaderChain(['bsie.reader.stat.Stat', 'bsie.reader.path.Invalid'], {})
+            self.assertEqual(chain._children, (bsie.reader.stat.Stat(), ))
+        # warning is issued if there are no subreaders
+        with self.assertLogs(logging.getLogger('bsie.reader.chain'), logging.WARNING):
+            chain = ReaderChain([], {})
+            self.assertEqual(chain._children, tuple())
+
+    def test_essentials(self):
+        chain = ReaderChain(['bsie.reader.stat.Stat', 'bsie.reader.path.Path'], {})
+        # identity
+        self.assertEqual(chain, chain)
+        self.assertEqual(hash(chain), hash(chain))
+        # comparison works across instances
+        self.assertEqual(chain,
+            ReaderChain(['bsie.reader.stat.Stat', 'bsie.reader.path.Path'], {}))
+        self.assertEqual(hash(chain),
+            hash(ReaderChain(['bsie.reader.stat.Stat', 'bsie.reader.path.Path'], {})))
+        # comparison respects subreaders
+        self.assertNotEqual(hash(chain),
+            hash(ReaderChain(['bsie.reader.path.Path'], {})))
+        self.assertNotEqual(hash(chain),
+            hash(ReaderChain(['bsie.reader.path.Path'], {})))
+        # comparison respects subreader order
+        self.assertNotEqual(chain,
+            ReaderChain(['bsie.reader.path.Path', 'bsie.reader.stat.Stat'], {}))
+        self.assertNotEqual(hash(chain),
+            hash(ReaderChain(['bsie.reader.path.Path', 'bsie.reader.stat.Stat'], {})))
+        # string representation
+        self.assertEqual(str(chain), 'ReaderChain(Stat, Path)')
+        self.assertEqual(repr(chain), 'ReaderChain((Stat(), Path()))')
+
+    def test_call(self):
+        chain = ReaderChain(['bsie.reader.stat.Stat', 'bsie.reader.path.Path'], {})
+        # chain first probes first child
+        self.assertEqual(chain(__file__), os.stat(__file__))
+        # chain probes second child if first one failes
+        self.assertEqual(chain(''), '')
+        self.assertEqual(chain('missing-file'), 'missing-file')
+
+        # chain raises a ReaderError if childs were exhausted
+        chain = ReaderChain(['bsie.reader.stat.Stat'], {})
+        # chain probes second child if first one failes
+        self.assertRaises(errors.ReaderError, chain, '')
+
+
+## main ##
+
+if __name__ == '__main__':
+    unittest.main()
+
+## EOF ##