Added a data() method to exiv2.BasicIo

This returns a simple context manager object that provides a memoryview
object when it is used in a with statement.

Author: jim-easterbrook

USAGE.rst

@@ -390,6 +390,14 @@ Doing so will invalidate the memoryview and may cause a segmentation fault:
     buf.alloc(128)
     print(bytes(data))              # Prints random values, may segfault
 
+A good way to ensure the memoryview_ object is ephemeral is to use it in a ``with`` statement:
+
+.. code:: python
+
+    buf = exiv2.DataBuf(b'fred')
+    with buf.data() as data:
+        print(bytes(data))              # Prints b'fred'
+
 Buffer interface
 ----------------
 
@@ -439,7 +447,17 @@ A Python `context manager`_ can be used to ensure that the ``open()`` and ``mmap
     with get_file_data(image) as data:
         rsp = requests.post(url, files={'file': io.BytesIO(data)})
 
-The ``exiv2.BasicIo`` Python type exposes a `buffer interface`_ which is a lot easier to use.
+Since python-exiv2 v0.18.0 the ``exiv2.BasicIo.data()`` method provides a context manager that calls ``open``, ``mmap``, ``munmap``, and ``close`` for you:
+
+.. code:: python
+
+    # after setting some metadata
+    image.writeMetadata()
+    exiv_io = image.io()
+    with exiv_io.data() as data:
+        rsp = requests.post(url, files={'file': io.BytesIO(data)})
+
+The ``exiv2.BasicIo`` Python type also exposes a `buffer interface`_.
 It allows the ``exiv2.BasicIo`` object to be used anywhere that a `bytes-like object`_ is expected:
 
 .. code:: python

src/interface/basicio.i

@@ -1,6 +1,6 @@
 // python-exiv2 - Python interface to libexiv2
 // http://github.com/jim-easterbrook/python-exiv2
-// Copyright (C) 2022-24  Jim Easterbrook  [email protected]
+// Copyright (C) 2022-25  Jim Easterbrook  [email protected]
 //
 // This program is free software: you can redistribute it and/or modify
 // it under the terms of the GNU General Public License as published by
@@ -167,6 +167,75 @@ static void release_ptr(Exiv2::BasicIo* self) {
 }
 EXPOSE_OBJECT_BUFFER(Exiv2::BasicIo, true, true)
 
+// Wrapper class to provide a context manager for Exiv2::BasicIo::mmap
+%feature("docstring") DataContext "Data context manager.
+
+A simple context manager for *mmap* / *munmap* data access. The
+*__enter__* method returns a :py:class:`memoryview` of the data."
+%ignore DataContext::DataContext;
+%inline %{
+class DataContext {
+private:
+    Exiv2::BasicIo* parent;
+    bool isWriteable;
+    bool mapped;
+public:
+    DataContext(Exiv2::BasicIo* parent, bool isWriteable) :
+        parent(parent), isWriteable(isWriteable), mapped(false) {};
+    ~DataContext() {
+        if (mapped) {
+            SWIG_PYTHON_THREAD_BEGIN_ALLOW;
+            parent->munmap();
+            SWIG_PYTHON_THREAD_END_ALLOW;
+            parent->close();
+        }
+    };
+    PyObject* __enter__() {
+        SWIG_PYTHON_THREAD_BEGIN_ALLOW;
+        int error = parent->open();
+        if (error) {
+            SWIG_PYTHON_THREAD_END_ALLOW;
+            return PyErr_Format(
+                PyExc_RuntimeError, "open() returned %d", error);
+        }
+        char* ptr = (char*)parent->mmap(isWriteable);
+        SWIG_PYTHON_THREAD_END_ALLOW;
+        mapped = true;
+        return PyMemoryView_FromMemory(
+            ptr, ptr ? parent->size() : 0,
+            isWriteable ? PyBUF_WRITE : PyBUF_READ);
+    };
+    bool __exit__(PyObject* exc_type, PyObject* exc_val, PyObject* exc_tb) {
+        if (mapped) {
+            SWIG_PYTHON_THREAD_BEGIN_ALLOW;
+            parent->munmap();
+            mapped = false;
+            parent->close();
+            SWIG_PYTHON_THREAD_END_ALLOW;
+        }
+        return false;
+    };
+};
+%}
+
+// Add Exiv2::BasicIo::data() method to return a context manager
+%feature("docstring") Exiv2::BasicIo::data "Return a data context manager.
+
+This allows easy access to the data using a ``with`` statement.
+The context manager calls *mmap* when the context is entered and
+*munmap* when the context is exited.
+:type isWriteable: bool, optional
+:param isWriteable: Set to true if the data should be writeable
+    (default is false).
+:rtype: object
+:return: A context manager"
+%newobject Exiv2::BasicIo::data;
+%extend Exiv2::BasicIo {
+    DataContext* data(bool isWriteable) {
+        return new DataContext($self, isWriteable);
+    }
+}
+
 // Make enum more Pythonic
 DEFINE_CLASS_ENUM(BasicIo, Position, "Seek starting positions.",
     "beg", Exiv2::BasicIo::beg,