add extended custom target

now supports read and seek handlers on targets
on_finish renamed as on_end

Author: jcupitt

Diff for: CHANGELOG.rst

@@ -1,4 +1,6 @@
 # master 
+
+* add seek and end handlers for TargetCustom [jcupitt]
 
 ## Version 2.2.0 (released 18 Apr 2022)
 

Diff for: examples/connection.py

@@ -3,36 +3,63 @@
 import sys
 import pyvips
 
-input_file = open(sys.argv[1], "rb")
-
-
-def read_handler(size):
-    return input_file.read(size)
-
-
-def seek_handler(offset, whence):
-    input_file.seek(offset, whence)
-    return input_file.tell()
-
-
-source = pyvips.SourceCustom()
-source.on_read(read_handler)
-source.on_seek(seek_handler)
-
-output_file = open(sys.argv[2], "wb")
-
-
-def write_handler(chunk):
-    return output_file.write(chunk)
-
-
-def finish_handler():
-    output_file.close()
-
-
-target = pyvips.TargetCustom()
-target.on_write(write_handler)
-target.on_finish(finish_handler)
-
+if len(sys.argv) != 4:
+    print(f"usage: {sys.argv[0]} IN-FILE OUT-FILE FORMAT")
+    print(f"   eg.: {sys.argv[0]} ~/pics/k2.jpg x .tif[tile]")
+    sys.exit(1)
+
+def source_custom(filename):
+    input_file = open(sys.argv[1], "rb")
+
+    def read_handler(size):
+        return input_file.read(size)
+
+    # seek is optional, but may improve performance by reducing buffering
+    def seek_handler(offset, whence):
+        input_file.seek(offset, whence)
+        return input_file.tell()
+
+    source = pyvips.SourceCustom()
+    source.on_read(read_handler)
+    source.on_seek(seek_handler)
+
+    return source
+
+def target_custom(filename):
+    # w+ means read and write ... we need to be able to read from our output
+    # stream for TIFF write
+    output_file = open(sys.argv[2], "w+b")
+
+    def write_handler(chunk):
+        return output_file.write(chunk)
+
+    # read and seek are optional and only needed for formats like TIFF
+    def read_handler(size):
+        return output_file.read(size)
+
+    def seek_handler(offset, whence):
+        output_file.seek(offset, whence)
+        return output_file.tell()
+
+    def end_handler():
+        # you can't throw exceptions over on_ handlers, you must return an error
+        # code
+        try:
+            output_file.close()
+        except IOError:
+            return -1
+        else:
+            return 0
+
+    target = pyvips.TargetCustom()
+    target.on_write(write_handler)
+    target.on_read(read_handler)
+    target.on_seek(seek_handler)
+    target.on_end(end_handler)
+
+    return target
+
+source = source_custom(sys.argv[1])
+target = target_custom(sys.argv[2])
 image = pyvips.Image.new_from_source(source, '', access='sequential')
-image.write_to_target(target, '.png')
+image.write_to_target(target, sys.argv[3])

Diff for: pyvips/gobject.py

@@ -42,14 +42,14 @@ def _marshal_image_progress(vi, pointer, handle):
 if at_least_libvips(8, 9):
     if pyvips.API_mode:
         @ffi.def_extern()
-        def _marshal_read(source_custom, pointer, length, handle):
+        def _marshal_read(gobject, pointer, length, handle):
             buf = ffi.buffer(pointer, length)
             callback = ffi.from_handle(handle)
             return callback(buf)
         _marshal_read_cb = ffi.cast('GCallback', gobject_lib._marshal_read)
     else:
         @ffi.callback('gint64(VipsSourceCustom*, void*, gint64, void*)')
-        def _marshal_read(source_custom, pointer, length, handle):
+        def _marshal_read(gobject, pointer, length, handle):
             buf = ffi.buffer(pointer, length)
             callback = ffi.from_handle(handle)
             return callback(buf)
@@ -58,30 +58,29 @@ def _marshal_read(source_custom, pointer, length, handle):
 
     if pyvips.API_mode:
         @ffi.def_extern()
-        def _marshal_seek(source_custom, offset, whence, handle):
+        def _marshal_seek(gobject, offset, whence, handle):
             callback = ffi.from_handle(handle)
             return callback(offset, whence)
         _marshal_seek_cb = \
             ffi.cast('GCallback', gobject_lib._marshal_seek)
     else:
         @ffi.callback('gint64(VipsSourceCustom*, gint64, int, void*)')
-        def _marshal_seek(source_custom, offset, whence, handle):
+        def _marshal_seek(gobject, offset, whence, handle):
             callback = ffi.from_handle(handle)
             return callback(offset, whence)
         _marshal_seek_cb = ffi.cast('GCallback', _marshal_seek)
     _marshalers['seek'] = _marshal_seek_cb
 
     if pyvips.API_mode:
         @ffi.def_extern()
-        def _marshal_write(source_custom, pointer, length, handle):
+        def _marshal_write(gobject, pointer, length, handle):
             buf = ffi.buffer(pointer, length)
             callback = ffi.from_handle(handle)
-            result = callback(buf)
-            return result
+            return callback(buf)
         _marshal_write_cb = ffi.cast('GCallback', gobject_lib._marshal_write)
     else:
         @ffi.callback('gint64(VipsTargetCustom*, void*, gint64, void*)')
-        def _marshal_write(source_custom, pointer, length, handle):
+        def _marshal_write(gobject, pointer, length, handle):
             buf = ffi.buffer(pointer, length)
             callback = ffi.from_handle(handle)
             return callback(buf)
@@ -90,18 +89,33 @@ def _marshal_write(source_custom, pointer, length, handle):
 
     if pyvips.API_mode:
         @ffi.def_extern()
-        def _marshal_finish(source_custom, handle):
+        def _marshal_finish(gobject, handle):
             callback = ffi.from_handle(handle)
             callback()
         _marshal_finish_cb = ffi.cast('GCallback', gobject_lib._marshal_finish)
     else:
         @ffi.callback('void(VipsTargetCustom*, void*)')
-        def _marshal_finish(source_custom, handle):
+        def _marshal_finish(gobject, handle):
             callback = ffi.from_handle(handle)
             callback()
         _marshal_finish_cb = ffi.cast('GCallback', _marshal_finish)
     _marshalers['finish'] = _marshal_finish_cb
 
+if at_least_libvips(8, 13):
+    if pyvips.API_mode:
+        @ffi.def_extern()
+        def _marshal_end(gobject, handle):
+            callback = ffi.from_handle(handle)
+            return callback()
+        _marshal_end_cb = ffi.cast('GCallback', gobject_lib._marshal_end)
+    else:
+        @ffi.callback('int(VipsTargetCustom*, void*)')
+        def _marshal_end(gobject, handle):
+            callback = ffi.from_handle(handle)
+            return callback()
+        _marshal_end_cb = ffi.cast('GCallback', _marshal_end)
+    _marshalers['end'] = _marshal_end_cb
+
 
 class GObject(object):
     """Manage GObject lifetime.

Diff for: pyvips/vdecls.py

@@ -504,6 +504,13 @@ def cdefs(features):
 
         '''
 
+    if _at_least(features, 8, 13):
+        code += '''
+            extern "Python" int _marshal_end (VipsTarget*,
+                void*);
+
+        '''
+
     # we must only define these in API mode ... in ABI mode we need to call
     # these things earlier
     if features['api']:

Diff for: pyvips/vtargetcustom.py

@@ -3,7 +3,7 @@
 import logging
 
 import pyvips
-from pyvips import ffi, vips_lib
+from pyvips import ffi, vips_lib, at_least_libvips
 
 logger = logging.getLogger(__name__)
 
@@ -44,11 +44,68 @@ def interface_handler(buf):
 
         self.signal_connect("write", interface_handler)
 
+    def on_read(self, handler):
+        """Attach a read handler.
+
+        The interface is exactly as io.read(). The handler is given a number
+        of bytes to fetch, and should return a bytes-like object containing up
+        to that number of bytes. If there is no more data available, it should
+        return None.
+
+        Read handlers are optional for targets. If you do not set one, your 
+        target will be treated as unreadable and libvips will be unable to 
+        write some file types (just TIFF, as of the time of writing).
+
+        """
+
+        def interface_handler(buf):
+            chunk = handler(len(buf))
+            if chunk is None:
+                return 0
+
+            bytes_read = len(chunk)
+            buf[:bytes_read] = chunk
+
+            return bytes_read
+
+        self.signal_connect("read", interface_handler)
+
+    def on_seek(self, handler):
+        """Attach a seek handler.
+
+        The interface is the same as io.seek(), so the handler is passed
+        parameters for offset and whence with the same meanings.
+
+        However, the handler MUST return the new seek position. A simple way
+        to do this is to call io.tell() and return that result.
+
+        Seek handlers are optional. If you do not set one, your target will be
+        treated as unseekable and libvips will be unable to write some file
+        types (just TIFF, as of the time of writing).
+
+        """
+
+        self.signal_connect("seek", handler)
+
+    def on_end(self, handler):
+        """Attach an end handler.
+
+        This optional handler is called at the end of write. It should do any
+        cleaning up necessary, and return 0 on success and -1 on error. 
+
+        """
+
+        if not at_least_libvips(8, 13):
+            # fall back for older libvips
+            self.on_finish(handler)
+        else:
+            self.signal_connect("end", handler)
+
     def on_finish(self, handler):
         """Attach a finish handler.
 
-        This optional handler is called at the end of write. It should do any
-        cleaning up necessary.
+        For libvips 8.13 and later, this method is deprecated in favour of
+        :meth:`on_end`.
 
         """
 

Diff for: tests/test_connections.py

@@ -72,17 +72,22 @@ def seek_handler(offset, whence):
                         reason="requires libvips >= 8.9")
     def test_target_custom(self):
         filename = temp_filename(self.tempdir, '.png')
-        output_file = open(filename, "wb")
+        output_file = open(filename, "w+b")
 
         def write_handler(chunk):
             return output_file.write(chunk)
 
-        def finish_handler():
-            output_file.close()
+        def end_handler():
+            try:
+                output_file.close()
+            except IOError:
+                return -1
+            else:
+                return 0
 
         target = pyvips.TargetCustom()
         target.on_write(write_handler)
-        target.on_finish(finish_handler)
+        target.on_end(end_handler)
 
         image = pyvips.Image.new_from_file(JPEG_FILE, access='sequential')
         image.write_to_target(target, '.png')
@@ -92,6 +97,46 @@ def finish_handler():
 
         assert (image - image2).abs().max() == 0
 
+    @skip_if_no('jpegload')
+    @skip_if_no('tiffsave')
+    @pytest.mark.skipif(not pyvips.at_least_libvips(8, 13),
+                        reason="requires libvips >= 8.13")
+    def test_target_custom_seek(self):
+        filename = temp_filename(self.tempdir, '.png')
+        output_file = open(filename, "w+b")
+
+        def write_handler(chunk):
+            return output_file.write(chunk)
+
+        def read_handler(size):
+            return output_file.read(size)
+
+        def seek_handler(offset, whence):
+            output_file.seek(offset, whence)
+            return output_file.tell()
+
+        def end_handler():
+            try:
+                output_file.close()
+            except IOError:
+                return -1
+            else:
+                return 0
+
+        target = pyvips.TargetCustom()
+        target.on_write(write_handler)
+        target.on_read(read_handler)
+        target.on_seek(seek_handler)
+        target.on_end(end_handler)
+
+        image = pyvips.Image.new_from_file(JPEG_FILE, access='sequential')
+        image.write_to_target(target, '.tif')
+
+        image = pyvips.Image.new_from_file(JPEG_FILE, access='sequential')
+        image2 = pyvips.Image.new_from_file(filename, access='sequential')
+
+        assert (image - image2).abs().max() == 0
+
     # test webp as well, since that maps the stream rather than using read
 
     @skip_if_no('webpload')