src/ tests/ docs/: avoid crash if samples memoryview is used after Pixmap destruction.

This addresses #4155.

src/__init__.py:
    With .samples_mv, remember the memoryview and call its .release() method in
    Pixmap.__del__().
docs/pixmap.rst:
    Document improved behaviour of Pixmap.samples_mv. Also warn that
    Pixmap.samples_ptr is unsafe after destruction of the pixmap.
tests/test_pixmap.py:
    Added test_4155(), check we get ValueError when accessing memoryview after
    Pixmap is destroyed.

Author: julian-smith-artifex-com

docs/pixmap.rst

@@ -546,6 +546,9 @@ Have a look at the :ref:`FAQ` section to see some pixmap usage "at work".
          367 ns ± 1.75 ns per loop (mean ± std. dev. of 7 runs, 1000000 loops each)
          In [4]: %timeit len(pix.samples)
          3.52 ms ± 57.5 µs per loop (mean ± std. dev. of 7 runs, 100 loops each)
+      
+      After the Pixmap has been destroyed, any attempt to use the memoryview
+      will fail with ValueError.
 
       :type: memoryview
 
@@ -559,6 +562,9 @@ Have a look at the :ref:`FAQ` section to see some pixmap usage "at work".
          img = QtGui.QImage(pix.samples_ptr, pix.width, pix.height, format) # (2)
 
       Both of the above lead to the same Qt image, but (2) can be **many hundred times faster**, because it avoids an additional copy of the pixel area.
+      
+      Warning: after the Pixmap has been destroyed, the Python pointer will be
+      invalid and attempting to use it may crash the Python interpreter.
 
       :type: int
 

src/__init__.py

@@ -10059,6 +10059,9 @@ def __init__(self, *args):
         # data.  Doesn't seem to make much difference to Pixmap.set_pixel() so
         # not currently used.
         self._memory_view = None
+        
+        # Cache for property `self.samples_mv`.
+        self._samples_mv = None
 
     def __len__(self):
         return self.size
@@ -10339,7 +10342,13 @@ def samples_mv(self):
         '''
         Pixmap samples memoryview.
         '''
-        return mupdf.fz_pixmap_samples_memoryview(self.this)
+        # We remember the returned memoryview so that our `__del__()` can
+        # release it; otherwise accessing it after we have been destructed will
+        # fail, possibly crashing Python; this is #4155.
+        #
+        if self._samples_mv is None:
+            self._samples_mv = mupdf.fz_pixmap_samples_memoryview(self.this)
+        return self._samples_mv
 
     @property
     def samples_ptr(self):
@@ -10625,6 +10634,10 @@ def yres(self):
 
     width  = w
     height = h
+    
+    def __del__(self):
+        if self._samples_mv:
+            self._samples_mv.release()
 
 
 del Point

tests/test_pixmap.py

@@ -428,3 +428,21 @@ def test_3854():
         assert rms < 1
     else:
         assert rms == 0
+
+
+def test_4155():
+    path = os.path.normpath(f'{__file__}/../../tests/resources/test_3854.pdf')
+    with pymupdf.open(path) as document:
+        page = document[0]
+        pixmap = page.get_pixmap()
+        mv = pixmap.samples_mv
+        mvb1 = mv.tobytes()
+    del page
+    del pixmap
+    try:
+        mvb2 = mv.tobytes()
+    except ValueError as e:
+        print(f'Received exception: {e}')
+        assert 'operation forbidden on released memoryview object' in str(e)
+    else:
+        assert 0, f'Did not receive expected exception when using defunct memoryview.'