Add Image.data() method

This gives direct access to the image data and should allow BasicIo to
be removed from the Python interface in a year or two.

Author: jim-easterbrook

CHANGELOG.txt

@@ -35,9 +35,9 @@ Changes in v0.18.0:
   7/ Exiv2 struct member names with a trailing underscore have more Pythonic
      aliases without the underscore.
   8/ Add data() method to exiv2.PreviewImage, deprecate pData() method.
-  9/ BasicIo.read (& readOrThrow) now extract count from the buffer size.
- 10/ Invalidate data iterators if data is deleted. (Requires swig >= 4.4)
- 11/ Add __members__ attribute to exiv2 "data" structure types.
+  9/ Add data() method to exiv2.Image. This will replace using Image.io().
+ 10/ BasicIo.read (& readOrThrow) now extract count from the buffer size.
+ 11/ Invalidate data iterators if data is deleted. (Requires swig >= 4.4)
  12/ Deprecated iteration of exiv2 "data" structure types.
  13/ API CHANGE: exiv2.LogMsg.pythonHandler is replaced by exiv2.pythonHandler
 

USAGE.rst

@@ -401,28 +401,19 @@ The buffered data isn't actually read until ``Image::readMetadata`` is called, s
 When ``Image::writeMetadata`` is called exiv2 allocates a new block of memory to store the modified data.
 The ``Image::io`` method returns an `Exiv2::BasicIo`_ object that provides access to this data.
 
-The ``BasicIo::mmap`` and ``BasicIo::munmap`` methods allows access to the image file data without unnecessary copying.
+The ``BasicIo::mmap`` and ``BasicIo::munmap`` methods allow access to the image file data without unnecessary copying.
 However they are rather error prone, crashing your Python program with a segmentation fault if anything goes wrong.
-Since python-exiv2 v0.18.0 it is much easier to use the ``data()`` method:
+
+Since python-exiv2 v0.18.0 it is much easier to use the image's ``data()`` method:
 
 .. code:: python
 
     # after setting some metadata
     image.writeMetadata()
-    exiv_io = image.io()
-    rsp = requests.post(url, files={'file': io.BytesIO(exiv_io.data())})
-
-The ``data()`` method can also return a writeable memoryview_:
-
-.. code:: python
-
-    exiv_io = image.io()
-    data = exiv_io.data(True)
-    data[23] = 157          # modifies data buffer
-    del data                # writes modified data to the buffer
-    image.readMetadata()    # reads modified buffer data
+    rsp = requests.post(url, files={'file': io.BytesIO(image.data())})
 
-The modified data is written back to the file or memory buffer when the memoryview_ is deleted.
+The ``data()`` method returns a Python memoryview_ that can be used in most places where a `bytes-like object`_ is expected.
+This allows copy free access to the image data.
 
 .. _bytearray:
     https://docs.python.org/3/library/stdtypes.html#bytearray

src/interface/image.i

@@ -76,6 +76,46 @@ INPUT_BUFFER_RO(const Exiv2::byte* data, BUFLEN_T size,
 // Release memory buffer after writeMetadata, as it creates its own copy
 RELEASE_BUFFER(void writeMetadata)
 
+// Add Image::data() method for easy data access to image data
+%feature("docstring") Exiv2::Image::data
+"Easy access to the image data.
+
+Calls io().open() & io().mmap() and returns a Python memoryview of the
+data. io().munmap() & io().close() are called when the memoryview object
+is deleted.
+
+This is intended to replace using Image.io() to get a BasicIo object,
+then accessing its data. BasicIo will eventually be removed from the
+Python interface.
+
+:rtype: memoryview"
+%extend Exiv2::Image {
+    %fragment("memoryview_funcs");
+    PyObject* data(PyObject* py_self) {
+        Exiv2::BasicIo& io = self->io();
+        SWIG_PYTHON_THREAD_BEGIN_ALLOW;
+        io.open();
+        Exiv2::byte* ptr = io.mmap(false);
+        SWIG_PYTHON_THREAD_END_ALLOW;
+        PyObject* result = PyMemoryView_FromMemory(
+            (char*)ptr, io.size(), PyBUF_READ);
+        if (store_view(py_self, result))
+            return NULL;
+        return result;
+    }
+}
+%fragment("release_ptr"{Exiv2::BasicIo});
+DEFINE_VIEW_CALLBACK(Exiv2::Image, release_ptr(&self->io());)
+%{
+#define RELEASE_VIEWS_Image_readMetadata
+#define RELEASE_VIEWS_Image_writeMetadata
+%}
+%typemap(check, fragment="memoryview_funcs") Exiv2::Image* self {
+%#ifdef RELEASE_VIEWS_$symname
+    release_views(self);
+%#endif
+}
+
 // Convert path encoding on Windows
 WINDOWS_PATH(const std::string& path)