add invalidate() method (#317)

* add invalidate() method

useful if you're modifying image memory arrays outside libvips, eg. with
numpy

see #316

* add rob's invalidate test

CHANGELOG.rst

@@ -2,12 +2,13 @@
 
 ## Version 2.1.17 (15 Dec 2021)
 
-* add `to_array()` [jcupitt]
+* add `toarray()` [jcupitt]
 * `repr()` will print matrix images as matrices [jcupitt]
 * more robust bandwise index/slice; added fancy slicing (step != 1) [erdmann]
 * fig segfault for `im.bandjoin([])`.  Now returns `im` [erdmann]
 * add numpy-style extended indexing (index with list of ints or bools) [erdmann]
 * earlier detection of unknown methods and class methods [jcupitt]
+* add `invalidate()` [jcupitt]
 
 ## Version 2.1.16 (28 Jun 2021)
 

pyvips/vdecls.py

@@ -211,6 +211,8 @@ def cdefs(features):
         void g_object_get_property (GObject* object,
             const char* name, GValue* value);
 
+        void vips_image_invalidate_all (VipsImage* image);
+
         typedef void (*GCallback)(void);
         typedef void (*GClosureNotify)(void* data, struct _GClosure *);
         long g_signal_connect_data (GObject* object,

pyvips/vimage.py

@@ -718,6 +718,23 @@ def write(self, other):
         if result != 0:
             raise Error('unable to write to image')
 
+    def invalidate(self):
+        """Drop caches on an image, and any downstream images.
+
+        This method drops all pixel caches on an image and on all downstream
+        images. Any operations which depend on this image, directly or
+        indirectly, are also dropped from the libvips operation cache.
+
+        This method can be useful if you wrap a libvips image around an area
+        of memory with :meth:`.new_from_memory` and then change some bytes
+        without libvips knowing.
+
+        Returns:
+            None
+
+        """
+        vips_lib.vips_image_invalidate_all(self.pointer)
+
     def set_progress(self, progress):
         """Enable progress reporting on an image.
 

tests/test_image.py

@@ -168,3 +168,19 @@ def test_bandslice(self):
             wrongargtype = dict(a=1, b=2)
             x = im[wrongargtype]
 
+        def test_invalidate(self):
+            try:
+                import numpy as np
+            except ImportError:
+                pytest.skip('numpy not available')
+
+            a = np.zeros((1,1))
+            p = pyvips.Image.new_from_memory(a.data, 1, 1, 1, 'double')
+            v = p(0, 0)
+            assert v == [0]
+            a[0,0] = 1
+            v = p(0, 0)
+            assert v == [0]
+            p.invalidate()
+            v = p(0, 0)
+            assert v == [1]