Deprecate use of BasicIo objects

Author: jim-easterbrook

CHANGELOG.txt

@@ -16,6 +16,12 @@ You should have received a copy of the GNU General Public License
 along with this program.  If not, see
 <http://www.gnu.org/licenses/>.
 
+Changes in v0.20.0:
+  1/ Deprecate all use of BasicIo objects. Please let me know if this is a
+     problem.
+  2/ Initialise XMP toolkit on startup and deprecate XmpParser.initialize
+  3/ Improved thread safety.
+
 Changes in v0.19.2:
   1/ Binary wheels incorporate libexiv2 v0.28.9
 

USAGE.rst

@@ -399,7 +399,7 @@ In python-exiv2 the ``data`` and ``size`` parameters are replaced with a single
 The buffered data isn't actually read until ``Image::readMetadata`` is called, so python-exiv2 stores a reference to the buffer to stop the user accidentally deleting it.
 
 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 deprecated ``Image::io`` method returns an `Exiv2::BasicIo`_ object that provides access to this data.
 
 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.

src/interface/image.i

@@ -131,6 +131,13 @@ WINDOWS_PATH(const std::string& path)
 %typemap(default) bool enable {$1 = true;}
 %ignore Exiv2::enableBMFF();
 
+// Deprecate methods that return a BasicIo object
+// Deprecated since 2026-09-01
+DEPRECATE_FUNCTION(Exiv2::Image::io, true)
+DEPRECATE_FUNCTION(Exiv2::ImageFactory::checkType, true)
+DEPRECATE_FUNCTION(Exiv2::ImageFactory::createIo, true)
+DEPRECATE_FUNCTION(Exiv2::ImageFactory::getType(BasicIo&), true)
+
 // Extend ImageFactory to allow creation of a MemIo from a buffer
 %feature("docstring") Exiv2::ImageFactory::createIo "
 *Overload 1:*

src/swig-0_27_7/image_wrap.cxx

@@ -6402,6 +6402,7 @@ SWIGINTERN PyObject *_wrap_Image_io(PyObject *self, PyObject *args) {
 #endif
   }
   {
+    PyErr_WarnEx(PyExc_DeprecationWarning, "Python scripts should not need to call ""Exiv2::Image::io", 1);
     try {
       result = (Exiv2::BasicIo *) &((Exiv2::Image const *)arg1)->io();
     }
@@ -6816,6 +6817,7 @@ SWIGINTERN PyObject *_wrap_ImageFactory_createIo__SWIG_0(PyObject *self, Py_ssiz
 #endif
   }
   {
+    PyErr_WarnEx(PyExc_DeprecationWarning, "Python scripts should not need to call ""Exiv2::ImageFactory::createIo", 1);
     try {
       result = Exiv2::ImageFactory::createIo((std::string const &)*arg1,arg2);
     }
@@ -7251,6 +7253,7 @@ SWIGINTERN PyObject *_wrap_ImageFactory_getType__SWIG_2(PyObject *self, Py_ssize
   }
   arg1 = reinterpret_cast< Exiv2::BasicIo * >(argp1);
   {
+    PyErr_WarnEx(PyExc_DeprecationWarning, "Python scripts should not need to call ""Exiv2::ImageFactory::getType(BasicIo&)", 1);
     try {
       result = (int)Exiv2::ImageFactory::getType(*arg1);
     }
@@ -7409,6 +7412,7 @@ SWIGINTERN PyObject *_wrap_ImageFactory_checkType(PyObject *self, PyObject *args
   } 
   arg3 = static_cast< bool >(val3);
   {
+    PyErr_WarnEx(PyExc_DeprecationWarning, "Python scripts should not need to call ""Exiv2::ImageFactory::checkType", 1);
     try {
       result = (bool)Exiv2::ImageFactory::checkType(arg1,*arg2,arg3);
     }
@@ -7448,6 +7452,7 @@ SWIGINTERN PyObject *_wrap_ImageFactory_createIo__SWIG_1(PyObject *self, Py_ssiz
     arg2 = (long) buff->len;
   }
   {
+    PyErr_WarnEx(PyExc_DeprecationWarning, "Python scripts should not need to call ""Exiv2::ImageFactory::createIo", 1);
     try {
       result = Exiv2_ImageFactory_createIo__SWIG_1((unsigned char const *)arg1,arg2);
     }

src/swig-0_28_7/image_wrap.cxx

@@ -6456,6 +6456,7 @@ SWIGINTERN PyObject *_wrap_Image_io(PyObject *self, PyObject *args) {
 #endif
   }
   {
+    PyErr_WarnEx(PyExc_DeprecationWarning, "Python scripts should not need to call ""Exiv2::Image::io", 1);
     try {
       result = (Exiv2::BasicIo *) &((Exiv2::Image const *)arg1)->io();
     }
@@ -6870,6 +6871,7 @@ SWIGINTERN PyObject *_wrap_ImageFactory_createIo__SWIG_0(PyObject *self, Py_ssiz
 #endif
   }
   {
+    PyErr_WarnEx(PyExc_DeprecationWarning, "Python scripts should not need to call ""Exiv2::ImageFactory::createIo", 1);
     try {
       result = Exiv2::ImageFactory::createIo((std::string const &)*arg1,arg2);
     }
@@ -7309,6 +7311,7 @@ SWIGINTERN PyObject *_wrap_ImageFactory_getType__SWIG_2(PyObject *self, Py_ssize
   }
   arg1 = reinterpret_cast< Exiv2::BasicIo * >(argp1);
   {
+    PyErr_WarnEx(PyExc_DeprecationWarning, "Python scripts should not need to call ""Exiv2::ImageFactory::getType(BasicIo&)", 1);
     try {
       result = (Exiv2::ImageType)Exiv2::ImageFactory::getType(*arg1);
     }
@@ -7467,6 +7470,7 @@ SWIGINTERN PyObject *_wrap_ImageFactory_checkType(PyObject *self, PyObject *args
   } 
   arg3 = static_cast< bool >(val3);
   {
+    PyErr_WarnEx(PyExc_DeprecationWarning, "Python scripts should not need to call ""Exiv2::ImageFactory::checkType", 1);
     try {
       result = (bool)Exiv2::ImageFactory::checkType(arg1,*arg2,arg3);
     }
@@ -7506,6 +7510,7 @@ SWIGINTERN PyObject *_wrap_ImageFactory_createIo__SWIG_1(PyObject *self, Py_ssiz
     arg2 = (size_t) buff->len;
   }
   {
+    PyErr_WarnEx(PyExc_DeprecationWarning, "Python scripts should not need to call ""Exiv2::ImageFactory::createIo", 1);
     try {
       result = Exiv2_ImageFactory_createIo__SWIG_1((unsigned char const *)arg1,SWIG_STD_MOVE(*(&arg2)));
     }

src/swig-0_28_9/image_wrap.cxx

@@ -6456,6 +6456,7 @@ SWIGINTERN PyObject *_wrap_Image_io(PyObject *self, PyObject *args) {
 #endif
   }
   {
+    PyErr_WarnEx(PyExc_DeprecationWarning, "Python scripts should not need to call ""Exiv2::Image::io", 1);
     try {
       result = (Exiv2::BasicIo *) &((Exiv2::Image const *)arg1)->io();
     }
@@ -6870,6 +6871,7 @@ SWIGINTERN PyObject *_wrap_ImageFactory_createIo__SWIG_0(PyObject *self, Py_ssiz
 #endif
   }
   {
+    PyErr_WarnEx(PyExc_DeprecationWarning, "Python scripts should not need to call ""Exiv2::ImageFactory::createIo", 1);
     try {
       result = Exiv2::ImageFactory::createIo((std::string const &)*arg1,arg2);
     }
@@ -7309,6 +7311,7 @@ SWIGINTERN PyObject *_wrap_ImageFactory_getType__SWIG_2(PyObject *self, Py_ssize
   }
   arg1 = reinterpret_cast< Exiv2::BasicIo * >(argp1);
   {
+    PyErr_WarnEx(PyExc_DeprecationWarning, "Python scripts should not need to call ""Exiv2::ImageFactory::getType(BasicIo&)", 1);
     try {
       result = (Exiv2::ImageType)Exiv2::ImageFactory::getType(*arg1);
     }
@@ -7467,6 +7470,7 @@ SWIGINTERN PyObject *_wrap_ImageFactory_checkType(PyObject *self, PyObject *args
   } 
   arg3 = static_cast< bool >(val3);
   {
+    PyErr_WarnEx(PyExc_DeprecationWarning, "Python scripts should not need to call ""Exiv2::ImageFactory::checkType", 1);
     try {
       result = (bool)Exiv2::ImageFactory::checkType(arg1,*arg2,arg3);
     }
@@ -7506,6 +7510,7 @@ SWIGINTERN PyObject *_wrap_ImageFactory_createIo__SWIG_1(PyObject *self, Py_ssiz
     arg2 = (size_t) buff->len;
   }
   {
+    PyErr_WarnEx(PyExc_DeprecationWarning, "Python scripts should not need to call ""Exiv2::ImageFactory::createIo", 1);
     try {
       result = Exiv2_ImageFactory_createIo__SWIG_1((unsigned char const *)arg1,SWIG_STD_MOVE(*(&arg2)));
     }

tests/test_basicio.py

@@ -55,7 +55,8 @@ def setUpClass(cls):
     def test_CurlIo(self):
         https_image = ('https://raw.githubusercontent.com/jim-easterbrook'
                        '/python-exiv2/main/tests/image_02.jpg')
-        io = exiv2.ImageFactory.createIo(https_image)
+        with self.assertWarns(DeprecationWarning):
+            io = exiv2.ImageFactory.createIo(https_image)
         self.assertIsInstance(io, exiv2.BasicIo)
         self.assertEqual(io.ioType(), 'CurlIo')
         self.assertEqual(io.error(), False)
@@ -79,7 +80,8 @@ def test_CurlIo(self):
                          'EXV_ENABLE_FILESYSTEM is off')
     def test_FileIo(self):
         # most functions are tested in test_MemIo
-        io = exiv2.ImageFactory.createIo(self.image_path)
+        with self.assertWarns(DeprecationWarning):
+            io = exiv2.ImageFactory.createIo(self.image_path)
         self.assertIsInstance(io, exiv2.BasicIo)
         self.assertEqual(io.ioType(), 'FileIo')
         self.assertEqual(io.error(), False)
@@ -94,7 +96,8 @@ def test_FileIo(self):
 
     def test_MemIo(self):
         # empty buffer
-        io = exiv2.ImageFactory.createIo(b'')
+        with self.assertWarns(DeprecationWarning):
+            io = exiv2.ImageFactory.createIo(b'')
         self.assertIsInstance(io, exiv2.BasicIo)
         self.assertEqual(io.ioType(), 'MemIo')
         self.assertEqual(io.size(), 0)
@@ -139,7 +142,8 @@ def test_MemIo(self):
             with self.assertRaises(IndexError):
                 view[0] = 0
         # non-empty buffer
-        io = exiv2.ImageFactory.createIo(self.data)
+        with self.assertWarns(DeprecationWarning):
+            io = exiv2.ImageFactory.createIo(self.data)
         self.assertIsInstance(io, exiv2.BasicIo)
         self.assertEqual(io.ioType(), 'MemIo')
         self.assertEqual(io.error(), False)
@@ -253,7 +257,8 @@ def test_ref_counts(self):
         if count > 1000000:
             # self.data is "immortal"
             return
-        io = exiv2.ImageFactory.createIo(self.data)
+        with self.assertWarns(DeprecationWarning):
+            io = exiv2.ImageFactory.createIo(self.data)
         self.assertEqual(sys.getrefcount(self.data), count + 1)
         del io
         self.assertEqual(sys.getrefcount(self.data), count)
@@ -272,7 +277,8 @@ def test_unicode_paths(self):
                     tmp_path = os.path.normcase(
                         os.path.join(tmp_dir, file_name))
                     shutil.copyfile(self.image_path, tmp_path)
-                    io = exiv2.ImageFactory.createIo(tmp_path)
+                    with self.assertWarns(DeprecationWarning):
+                        io = exiv2.ImageFactory.createIo(tmp_path)
                     if cp in codes:
                         self.assertEqual(io.path(), tmp_path)
                     else:

tests/test_image.py

@@ -62,7 +62,8 @@ def test_BMFF(self):
     def test_Image(self):
         # open image in memory so we don't corrupt the file
         image = exiv2.ImageFactory.open(self.image_data)
-        self.assertEqual(len(image.io()), 15125)
+        with self.assertWarns(DeprecationWarning):
+            self.assertEqual(len(image.io()), 15125)
         # test clearMetadata
         image.readMetadata()
         self.check_result(image.comment(), str, 'Created with GIMP')
@@ -77,7 +78,8 @@ def test_Image(self):
         self.assertEqual(len(image.xmpData()), 0)
         self.assertEqual(len(image.iccProfile()), 0)
         image.writeMetadata()
-        self.assertEqual(len(image.io()), 6371)
+        with self.assertWarns(DeprecationWarning):
+            self.assertEqual(len(image.io()), 6371)
         # test setting individual parts
         image2 = exiv2.ImageFactory.open(self.image_data)
         image2.readMetadata()
@@ -96,7 +98,8 @@ def test_Image(self):
         self.assertEqual(len(image.iccProfile()), 672)
         image.writeMetadata()
         data_len = (15125, 15174)[exiv2.testVersion(0, 28, 9)]
-        self.assertEqual(len(image.io()), data_len)
+        with self.assertWarns(DeprecationWarning):
+            self.assertEqual(len(image.io()), data_len)
         del image2
         # test clearing individual parts
         image = exiv2.ImageFactory.open(self.image_data)
@@ -148,7 +151,8 @@ def test_Image(self):
         self.check_result(image.iccProfileDefined(), bool, True)
         self.check_result(image.imageType(),
                           exiv2.ImageType, exiv2.ImageType.jpeg)
-        self.assertIsInstance(image.io(), exiv2.BasicIo)
+        with self.assertWarns(DeprecationWarning):
+            self.assertIsInstance(image.io(), exiv2.BasicIo)
         self.check_result(image.mimeType(), str, 'image/jpeg')
         self.check_result(image.pixelHeight(), int, 200)
         self.check_result(image.pixelWidth(), int, 200)
@@ -163,28 +167,35 @@ def test_ImageFactory(self):
         self.check_result(
             factory.checkMode(exiv2.ImageType.jpeg, exiv2.MetadataId.Exif),
             exiv2.AccessMode, exiv2.AccessMode.ReadWrite)
-        io = factory.createIo(self.image_data)
+        with self.assertWarns(DeprecationWarning):
+            io = factory.createIo(self.image_data)
         with self.assertWarns(DeprecationWarning):
             factory.checkType(int(exiv2.ImageType.jpeg), io, False)
-        self.check_result(
-            factory.checkType(exiv2.ImageType.jpeg, io, False), bool, True)
+        with self.assertWarns(DeprecationWarning):
+            self.check_result(
+                factory.checkType(exiv2.ImageType.jpeg, io, False), bool, True)
         with self.assertWarns(DeprecationWarning):
             factory.create(int(exiv2.ImageType.jpeg))
         self.assertIsInstance(
             factory.create(exiv2.ImageType.jpeg), exiv2.Image)
-        self.assertIsInstance(factory.createIo(self.image_data), exiv2.BasicIo)
+        with self.assertWarns(DeprecationWarning):
+            self.assertIsInstance(
+                factory.createIo(self.image_data), exiv2.BasicIo)
         self.check_result(factory.getType(self.image_data),
                           exiv2.ImageType, exiv2.ImageType.jpeg)
-        self.check_result(factory.getType(io),
-                          exiv2.ImageType, exiv2.ImageType.jpeg)
+        with self.assertWarns(DeprecationWarning):
+            self.check_result(factory.getType(io),
+                              exiv2.ImageType, exiv2.ImageType.jpeg)
         self.assertIsInstance(factory.open(self.image_data), exiv2.Image)
         if not exiv2.versionInfo()['EXV_ENABLE_FILESYSTEM']:
             self.skipTest('EXV_ENABLE_FILESYSTEM is off')
         with tempfile.TemporaryDirectory() as tmp_dir:
             temp_file = os.path.join(tmp_dir, 'image.jpg')
             self.assertIsInstance(
                 factory.create(exiv2.ImageType.jpeg, temp_file), exiv2.Image)
-        self.assertIsInstance(factory.createIo(self.image_path), exiv2.BasicIo)
+        with self.assertWarns(DeprecationWarning):
+            self.assertIsInstance(
+                factory.createIo(self.image_path), exiv2.BasicIo)
         self.check_result(factory.getType(self.image_path),
                           exiv2.ImageType, exiv2.ImageType.jpeg)
         self.assertIsInstance(factory.open(self.image_path), exiv2.Image)
@@ -210,7 +221,8 @@ def test_ref_counts(self):
         self.assertEqual(sys.getrefcount(image), count + 3)
         data.append(image.iccProfile())
         self.assertEqual(sys.getrefcount(image), count + 4)
-        data.append(image.io())
+        with self.assertWarns(DeprecationWarning):
+            data.append(image.io())
         self.assertEqual(sys.getrefcount(image), count + 5)
         data.append(image.data())
         self.assertEqual(sys.getrefcount(image), count + 6)