Merge pull request #53 from jim-easterbrook/devel

Devel

Author: jim-easterbrook

.github/workflows/test-interface.yml

@@ -31,8 +31,6 @@ jobs:
         python-version: ['3.8', '3.9', '3.10', '3.11', '3.12']
         os: [ubuntu-latest]
         include:
-          - python-version: '3.6'
-            os: ubuntu-20.04
           - python-version: '3.7'
             os: ubuntu-22.04
     runs-on: ${{ matrix.os }}

.gitignore

@@ -1,4 +1,4 @@
-/build
+/build*
 /doc
 /dist
 /src/doc/api

CHANGELOG.txt

@@ -16,6 +16,39 @@ 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.18.0:
+  1/ Removed features deprecated in v0.13.0:
+     Value (and derived types) copy constructors
+     Single value (such as DateValue) index methods
+     DataBuf indexing.
+  2/ Deprecated many BasicIo methods (read, write, seek, etc.) that should not
+     be needed in Python scripts. Please let me know if this is a problem.
+  3/ Deprecated copy, write, and read(buffer) methods of Value (and
+     subclasses) that should not be needed in Python scripts. Please let me
+     know if this is a problem.
+  4/ Deprecated copy and write methods of Metadatum (and subclasses) that
+     should not be needed in Python scripts. Please let me know if this is a
+     problem.
+  5/ Deprecated 'buffer interface' to BasicIo, DataBuf, and PreviewImage. They
+     all have 'data()' to get their contents.
+  6/ Added binary wheels for Linux on arm64.
+  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/ Add data() method to exiv2.Image. This will replace using Image.io().
+ 10/ Add data() method to exiv2.DataValue.
+ 11/ BasicIo.read (& readOrThrow) now extract count from the buffer size.
+ 12/ Invalidate data iterators if data is deleted. (Requires swig >= 4.4)
+ 13/ Deprecated iteration of exiv2 "data" structure types.
+ 14/ API CHANGE: exiv2.LogMsg.pythonHandler is replaced by exiv2.pythonHandler
+
+Changes in v0.17.5:
+  1/ Binary wheels incorporate libexiv2 v0.28.7.
+
+Changes in v0.17.4: (yanked)
+  1/ Binary wheels incorporate libexiv2 v0.28.6.
+  2/ Windows binary wheels do not have localisation.
+
 Changes in v0.17.3:
   1/ Binary wheels incorporate libexiv2 v0.28.5.
 

INSTALL.rst

@@ -21,7 +21,7 @@ Use installed libexiv2
 
 In the example above, pip_ installs a "binary wheel_".
 This is pre-compiled and includes a copy of the libexiv2_ library, which makes installation quick and easy.
-Wheels for `python-exiv2`_ are available for Windows, Linux, and MacOS with Python versions from 3.6 to 3.12.
+Wheels for `python-exiv2`_ are available for Windows, Linux, and MacOS with Python versions from 3.6 to 3.13.
 
 If your computer already has libexiv2_ installed (typically by your operating system's "package manager") then pip_ might be able to compile `python-exiv2`_ to use it.
 First you need to check what version of python-exiv2 you have::

README.rst

@@ -1,4 +1,4 @@
-python-exiv2 v\ 0.17.3
+python-exiv2 v\ 0.18.0
 ======================
 
 python-exiv2 is a low level interface (or binding) to the exiv2_ C++ library.
@@ -47,15 +47,17 @@ Please see `USAGE.rst`_ for more help with using the Python interface to libexiv
 Transition to libexiv2 v0.28.x
 ------------------------------
 
-Before python-exiv2 v0.16 the "binary wheels" available from PyPI_ incorporated libexiv2 v0.27.7 or earlier.
-Binary wheels for python-exiv2 v0.16.3 incorporate libexiv2 v0.28.2, and those for python-exiv2 v0.16.2 incorporate libexiv2 v0.27.7.
-Binary wheels for python-exiv2 v0.17.0 incorporate libexiv2 v0.28.3.
-If your software is currently incompatible with libexiv2 v0.28.x you can use the older version of libexiv2 by explicitly installing python-exiv2 v0.16.2::
+Since python-exiv2 v0.16.3 the "binary wheels" available from PyPI_ incorporate libexiv2 v0.28.2 or later.
+If your software is currently incompatible with libexiv2 v0.28.x you can use an older version of libexiv2 by explicitly installing python-exiv2 v0.16.2::
 
-    $ pip install --user exiv2==0.16.2
+    $ pip install --user exiv2==0.16.2 --only-binary :all:
+
+Alternatively, if you have libexiv2 v0.27.x and its "development headers" installed on your computer, you can install python-exiv2 from source using your system libexiv2::
+
+    $ pip install --user exiv2 --no-binary :all:
 
 There are some changes in the libexiv2 API between v0.27.7 and v0.28.x.
-Future versions of python-exiv2 will all incorporate libexiv2 v0.28.x, so please update your software to use the changed API.
+Eventually python-exiv2 will no longer support libexiv2 v0.27.x, so please update your software to use the changed API.
 
 Documentation
 -------------
@@ -97,6 +99,7 @@ Installation
 
 Python "binary wheels" are available for Windows, Linux, and MacOS.
 These include the libexiv2 library and should not need any other software to be installed.
+(Although on Windows you might need to update your `MSVC redistributable`_.)
 They can be installed with Python's pip_ package.
 For example, on Windows::
 
@@ -119,6 +122,8 @@ Please email [email protected] if you find any problems (or solutions!).
 .. _gexiv2:            https://wiki.gnome.org/Projects/gexiv2
 .. _GitHub:            https://github.com/jim-easterbrook/python-exiv2
 .. _libexiv2:          https://www.exiv2.org/doc/index.html
+.. _MSVC redistributable:
+    https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170#latest-microsoft-visual-c-redistributable-version
 .. _pip:               https://pip.pypa.io/
 .. _pyexiv2 (new):     https://github.com/LeoHsiao1/pyexiv2
 .. _pyexiv2 (old):     https://launchpad.net/pyexiv2

USAGE.rst

@@ -13,7 +13,7 @@ libexiv2 library version
 ------------------------
 
 Python-exiv2 can be used with any version of libexiv2 from 0.27.0 onwards.
-The "binary wheels" available from PyPI_ currently include a copy of libexiv2 v0.27.7, but if you install from source then python-exiv2 will use whichever version of libexiv2 is installed on your computer.
+The "binary wheels" available from PyPI_ currently include a copy of libexiv2 v0.28.5, but if you install from source then python-exiv2 will use whichever version of libexiv2 is installed on your computer.
 
 There are some differences in the API of libexiv2 v0.28.x and v0.27.y.
 Some of these have been "backported" in the Python interface so you can start using the v0.28 methods, e.g. the ``exiv2.DataBuf.data()`` function replaces the ``exiv2.DataBuf.pData_`` attribute.
@@ -51,27 +51,20 @@ Some parts of the interface are deprecated and will eventually be removed.
 Please use Python's ``-Wd`` flag when testing your software to ensure it isn't using deprecated features.
 (Do let me know if I've deprecated a feature you need and can't replace with an alternative.)
 
-Enums
------
-
-The C++ libexiv2 library often uses ``enum`` classes to list related data, such as the value type identifiers stored in `Exiv2::TypeId`_.
-SWIG's default processing of such enums is to add all the values as named constants to the top level of the module, e.g. ``exiv2.asciiString``.
-In python-exiv2 most of the C++ enums are represented by Python enum_ classes, e.g. ``exiv2.TypeId.asciiString`` is a member of ``exiv2.TypeId``.
-
-Unfortunately there is no easy way to deprecate the SWIG generated top level constants, but they will eventually be removed from python-exiv2.
-Please ensure you only use the enum classes in your use of python-exiv2.
-
 Data structures
 ---------------
 
 Some parts of the Exiv2 API use structures to hold several related data items.
 For example, the `Exiv2::ExifTags`_ class has a ``tagList()`` method that returns a list of `Exiv2::TagInfo`_ structs.
-In python-exiv2 (since v0.16.2) these structs have dict_ like behaviour, so the members can be accessed more easily:
+Since python-exiv2 v0.18.0 struct member names ending with an underscore ``_`` have aliases without the underscore.
+Since v0.16.2 these structs also have dict_ like behaviour, so the members can be accessed more easily:
 
 .. code:: python
 
     >>> import exiv2
     >>> info = exiv2.ExifTags.tagList('Image')[0]
+    >>> print(info.title)
+    Processing Software
     >>> print(info.title_)
     Processing Software
     >>> print(info['title'])
@@ -90,7 +83,8 @@ In python-exiv2 (since v0.16.2) these structs have dict_ like behaviour, so the
      'title': 'Processing Software',
      'typeId': <TypeId.asciiString: 2>}
 
-Note that struct member names ending with an underscore have the underscore removed in the dict_ like interface.
+In general it's more efficient to use attribute access (``info.title``) than dict_ access (``info['title']``).
+It is sometimes useful to be able to iterate over the members though, as shown above.
 
 Reading data values
 -------------------
@@ -107,7 +101,7 @@ The Python interface uses the value's ``typeId()`` method to determine its type
 Recasting data values
 ^^^^^^^^^^^^^^^^^^^^^
 
-In earlier versions of python-gphoto2 you could set the type of value returned by ``value()`` or ``getValue()`` by passing an ``exiv2.TypeId`` parameter:
+In old versions of python-gphoto2 you could set the type of value returned by ``value()`` or ``getValue()`` by passing an ``exiv2.TypeId`` parameter:
 
 .. code:: python
 
@@ -231,14 +225,16 @@ If you don't want to use the data numerically then you can just use strings for
     value = str(datum.value())
     exifData['Exif.GPSInfo.GPSLatitude'] = '47/1 49/1 31822/1000'
 
-Iterators
----------
+Iterators & references
+----------------------
 
 The ``Exiv2::ExifData``, ``Exiv2::IptcData``, and ``Exiv2::XmpData`` classes use C++ iterators to expose private data, for example the ``ExifData`` class has a private member of ``std::list<Exifdatum>`` type.
 The classes have public ``begin()``, ``end()``, and ``findKey()`` methods that return ``std::list`` iterators.
-In C++ you can dereference one of these iterators to access the ``Exifdatum`` object, but Python doesn't have a dereference operator.
+They also have ``[key]`` operators that return a pointer to an ``Exifdatum`` object.
+
+In C++ you can dereference one of these pointers to access the ``Exifdatum`` object, but Python doesn't have a dereference operator.
 
-This Python interface converts the ``std::list`` iterator to a Python object that has access to all the ``Exifdatum`` object's methods without dereferencing.
+In python-exiv2 the iterators (and references since v0.18.0) are wrapped in a Python object that has access to all the ``Exifdatum`` object's methods without dereferencing.
 For example:
 
 .. code:: python
@@ -311,29 +307,11 @@ This allows them to be used in a very Pythonic style:
 Warning: segmentation faults
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-If an iterator is invalidated, e.g. by deleting the datum it points to, then your Python program may crash with a segmentation fault if you try to use the invalid iterator.
-Just as in C++, there is no way to detect that an iterator has become invalid.
-
-Segmentation faults
--------------------
-
-There are many places in the libexiv2 C++ API where objects hold references to data in other objects.
-This is more efficient than copying the data, but can cause segmentation faults if an object is deleted while another objects refers to its data.
-
-The Python interface tries to protect the user from this but in some cases this is not possible.
-For example, an `Exiv2::Metadatum`_ object holds a reference to data that can easily be invalidated:
+If a pointer is invalidated, e.g. by deleting the datum it points to, then your Python program may crash with a segmentation fault if you try to use the invalid pointer.
+Just as in C++, there is no way to detect that a pointer has become invalid.
 
-.. code:: python
-
-    exifData = image.exifData()
-    datum = exifData['Exif.GPSInfo.GPSLatitude']
-    print(str(datum.value()))                       # no problem
-    del exifData['Exif.GPSInfo.GPSLatitude']
-    print(str(datum.value()))                       # segfault!
-
-Segmentation faults are also easily caused by careless use of iterators or memory blocks, as discussed below.
-There may be other cases where the Python interface doesn't prevent segfaults.
-Please let me know if you find any.
+Since v0.18.0 python-exiv2 (if built with swig >= 4.4) tries to invalidate pointers if the data they point to is deleted.
+Please let me know if you encounter any problems with segmentation faults.
 
 Binary data input
 -----------------
@@ -366,23 +344,36 @@ In some cases this includes writing to the data.
     buf = thumb.copy()
     thumb_im = PIL.Image.open(io.BytesIO(buf.data()))
 
-In python-exiv2 before v0.15.0 the memory block is converted to an object with a buffer interface.
-A Python memoryview_ can be used to access the data without copying.
-(Converting to bytes_ would make a copy of the data, which we don't usually want.)
+Since version 0.18.0 python-exiv2 releases the memoryview_ if the memory is invalidated (e.g. if the memory block is resized) to prevent problems such as segmentation faults:
 
-Warning: segmentation faults
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. code:: python
+
+    >>> buf = exiv2.DataBuf(b'fred')
+    >>> data = buf.data()
+    >>> print(bytes(data))
+    b'fred'
+    >>> buf.resize(128)
+    >>> print(bytes(data))
+    Traceback (most recent call last):
+      File "<stdin>", line 1, in <module>
+    ValueError: operation forbidden on released memoryview object
+    >>>
 
-Note that the memory block must not be deleted or resized while the memoryview exists.
-Doing so will invalidate the memoryview and may cause a segmentation fault:
+Although memoryview_ objects can be used in a with_ statement this has no benefit with python-exiv2.
+The memory view's ``release`` method does nothing.
+Releasing any associated resources only happens when the memory view is deleted:
 
 .. code:: python
 
-    buf = exiv2.DataBuf(b'fred')
-    data = buf.data()
-    print(bytes(data))              # Prints b'fred'
-    buf.alloc(128)
-    print(bytes(data))              # Prints random values, may segfault
+    with buf.data() as data:
+        file.write(data)
+    del data
+
+is equivalent to
+
+.. code:: python
+
+    file.write(buf.data())
 
 Buffer interface
 ----------------
@@ -398,6 +389,8 @@ For example, you could save a photograph's thumbnail in a separate file like thi
     with open('thumbnail.jpg', 'wb') as out_file:
         out_file.write(thumb.copy())
 
+Use of this buffer interface is deprecated (since python-exiv2 v0.18.0) and the ``data()`` methods described above should be used instead.
+
 Image data in memory
 --------------------
 
@@ -408,51 +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`` method allows access to the image file data without unnecessary copying.
-However it is rather error prone, crashing your Python program with a segmentation fault if anything goes wrong.
+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.
 
-The ``Exiv2::BasicIo`` object must be opened before calling ``mmap()``.
-A Python `context manager`_ can be used to ensure that the ``open()`` and ``mmap()`` calls are paired with ``munmap()`` and ``close()`` calls:
+Since python-exiv2 v0.18.0 it is much easier to use the image's ``data()`` method:
 
 .. code:: python
 
-    from contextlib import contextmanager
-
-    @contextmanager
-    def get_file_data(image):
-        exiv_io = image.io()
-        exiv_io.open()
-        try:
-            yield exiv_io.mmap()
-        finally:
-            exiv_io.munmap()
-            exiv_io.close()
-
     # after setting some metadata
     image.writeMetadata()
-    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.
-It allows the ``exiv2.BasicIo`` object to be used anywhere that a `bytes-like object`_ is expected:
-
-.. code:: python
-
-    # after setting some metadata
-    image.writeMetadata()
-    exiv_io = image.io()
-    rsp = requests.post(url, files={'file': io.BytesIO(exiv_io)})
-
-Since python-exiv2 v0.15.0 this buffer can be writeable:
-
-.. code:: python
-
-    exiv_io = image.io()
-    with memoryview(exiv_io) as data:
-        data[23] = 157      # modifies data 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 released.
+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
@@ -502,3 +463,5 @@ The modified data is written back to the file or memory buffer when the memoryvi
     https://docs.python.org/3/library/stdtypes.html#memoryview
 .. _PyPI:
     https://pypi.org/project/exiv2/
+.. _with:
+    https://docs.python.org/3/reference/compound_stmts.html#with