Add support for new illustrations APIs in libzim 9.4.0

Author: benoit74

.github/workflows/CI-wheels.yaml

@@ -7,7 +7,7 @@ on:
       - main
 
 env:
-  LIBZIM_DL_VERSION: "9.3.0-1"
+  LIBZIM_DL_VERSION: "9.4.0"
   MACOSX_DEPLOYMENT_TARGET: "13.0"
   CIBW_ENVIRONMENT_PASS_LINUX: "LIBZIM_DL_VERSION"
   CIBW_BUILD_VERBOSITY: "3"

.github/workflows/Publish.yaml

@@ -6,7 +6,7 @@ on:
       - published
 
 env:
-  LIBZIM_DL_VERSION: "9.3.0-1"
+  LIBZIM_DL_VERSION: "9.4.0"
   MACOSX_DEPLOYMENT_TARGET: "13.0"
   CIBW_ENVIRONMENT_PASS_LINUX: "LIBZIM_DL_VERSION"
   # APPLE_SIGNING_KEYCHAIN_PATH set in prepare keychain step

.github/workflows/QA.yaml

@@ -2,7 +2,7 @@ name: QA
 on: [push]
 
 env:
-  LIBZIM_DL_VERSION: "9.3.0-1"
+  LIBZIM_DL_VERSION: "9.4.0"
   MACOSX_DEPLOYMENT_TARGET: "13.0"
 
 jobs:

.github/workflows/Tests.yaml

@@ -2,7 +2,7 @@ name: Tests
 on: [push]
 
 env:
-  LIBZIM_DL_VERSION: "9.3.0-1"
+  LIBZIM_DL_VERSION: "9.4.0"
   MACOSX_DEPLOYMENT_TARGET: "13.0"
   # we want cython traces for coverage
   PROFILE: "1"

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- libzim 9.4.0 new illustration APIs (#232)
+
 ## [3.7.0] - 2025-04-18
 
 ### Added

libzim/libwrapper.h

@@ -26,6 +26,7 @@
 #include <zim/archive.h>
 #include <zim/entry.h>
 #include <zim/item.h>
+#include <zim/illustration.h>
 #include <zim/writer/item.h>
 #include <zim/writer/contentProvider.h>
 #include <zim/search.h>
@@ -106,6 +107,17 @@ class Blob : public Wrapper<zim::Blob>
     FORWARD(zim::size_type, size)
 };
 
+class IllustrationInfo : public Wrapper<zim::IllustrationInfo>
+{
+  public:
+    IllustrationInfo() = default;
+    IllustrationInfo(const zim::IllustrationInfo& o) : Wrapper(o) {}
+    IllustrationInfo(uint32_t width, uint32_t height, float scale) : Wrapper(zim::IllustrationInfo{width, height, scale}) {}
+    zim::IllustrationInfo& operator*() const { return *mp_base; }
+    operator zim::IllustrationInfo() const { return *mp_base; }
+    FORWARD(std::string, asMetadataItemName)
+};
+
 class Item : public Wrapper<zim::Item>
 {
   public:
@@ -147,6 +159,7 @@ class Archive : public Wrapper<zim::Archive>
     FORWARD(wrapper::Entry, getRandomEntry)
     FORWARD(wrapper::Item, getIllustrationItem)
     FORWARD(std::set<unsigned int>, getIllustrationSizes)
+    FORWARD(zim::IllustrationInfos, getIllustrationInfos)
     std::string getUuid() const
     { auto u = mp_base->getUuid();
       std::string uuids(u.data, u.size());

libzim/libzim.pyx

@@ -39,6 +39,7 @@ import os
 import pathlib
 import sys
 import traceback
+import warnings
 from collections import OrderedDict
 from types import ModuleType
 from typing import Dict, Generator, Iterator, List, Optional, Set, TextIO, Tuple, Union
@@ -373,20 +374,34 @@ cdef class _Creator:
         self.c_creator.setMainPath(mainPath.encode('UTF-8'))
         return self
 
-    def add_illustration(self, int size: pyint, content: bytes):
+    def add_illustration(self, size_or_info, content: bytes):
         """Add a PNG illustration to Archive.
 
         Refer to https://wiki.openzim.org/wiki/Metadata for more details.
 
         Args:
-            size (int): The width of the square PNG illustration in pixels.
+            size_or_info: Either an int (width of the square PNG illustration in pixels)
+                          or an IllustrationInfo object with width, height, and scale.
             content (bytes): The binary content of the PNG illustration.
 
         Raises:
-            RuntimeError: If an illustration with the same width already exists.
+            RuntimeError: If an illustration with the same attributes already exists.
+
+        Examples:
+            # Old style (square illustration at scale 1)
+            creator.add_illustration(48, png_data)
+
+            # New style (with dimensions and scale)
+            info = IllustrationInfo(48, 48, 2.0)
+            creator.add_illustration(info, png_data)
         """
         cdef string _content = content
-        self.c_creator.addIllustration(size, _content)
+        if isinstance(size_or_info, IllustrationInfo):
+            self.c_creator.addIllustration((<IllustrationInfo>size_or_info).c_info, _content)
+        elif isinstance(size_or_info, int):
+            self.c_creator.addIllustration(<int>size_or_info, _content)
+        else:
+            raise TypeError(f"First argument must be int or IllustrationInfo, not {type(size_or_info)}")
 
 #    def set_uuid(self, uuid) -> Creator:
 #        self.c_creator.setUuid(uuid)
@@ -819,6 +834,122 @@ cdef class ReadingBlob:
         self.view_count -= 1
 
 
+cdef class IllustrationInfo:
+    """Information about an illustration in a ZIM archive.
+
+    Attributes:
+        width (int): Width of the illustration in CSS pixels.
+        height (int): Height of the illustration in CSS pixels.
+        scale (float): Device pixel ratio (scale) of the illustration.
+        extra_attributes (dict): Additional attributes as key-value pairs.
+    """
+    __module__ = reader_module_name
+    cdef zim.IllustrationInfo c_info
+
+    def __cinit__(self, width: pyint = 0, height: pyint = 0, scale: float = 1.0):
+        """Create an IllustrationInfo.
+
+        Args:
+            width: Width of the illustration in CSS pixels.
+            height: Height of the illustration in CSS pixels.
+            scale: Device pixel ratio (default: 1.0).
+        """
+        if width or height:
+            self.c_info = move(zim.IllustrationInfo(width, height, scale))
+
+    @staticmethod
+    cdef from_illustration_info(zim.IllustrationInfo info):
+        """Creates a Python IllustrationInfo from a C++ IllustrationInfo.
+
+        Args:
+            info: A C++ IllustrationInfo
+
+        Returns:
+            IllustrationInfo: Casted illustration info
+        """
+        cdef IllustrationInfo ii = IllustrationInfo()
+        ii.c_info = move(info)
+        return ii
+
+    @staticmethod
+    def from_metadata_item_name(name: str) -> IllustrationInfo:
+        """Parse an illustration metadata item name into IllustrationInfo.
+
+        Args:
+            name: The metadata item name (e.g., "Illustration_48x48@2").
+
+        Returns:
+            The parsed IllustrationInfo.
+
+        Raises:
+            RuntimeError: If the name cannot be parsed.
+        """
+        cdef string _name = name.encode('UTF-8')
+        cdef zim.IllustrationInfo info = zim.IllustrationInfo.fromMetadataItemName(_name)
+        return IllustrationInfo.from_illustration_info(move(info))
+
+    @property
+    def width(self) -> pyint:
+        """Width of the illustration in CSS pixels."""
+        return self.c_info.width
+
+    @width.setter
+    def width(self, value: pyint):
+        self.c_info.width = value
+
+    @property
+    def height(self) -> pyint:
+        """Height of the illustration in CSS pixels."""
+        return self.c_info.height
+
+    @height.setter
+    def height(self, value: pyint):
+        self.c_info.height = value
+
+    @property
+    def scale(self) -> float:
+        """Device pixel ratio (scale) of the illustration."""
+        return self.c_info.scale
+
+    @scale.setter
+    def scale(self, value: float):
+        self.c_info.scale = value
+
+    @property
+    def extra_attributes(self) -> Dict[str, str]:
+        """Additional attributes as key-value pairs."""
+        result = {}
+        for item in self.c_info.extraAttributes:
+            result[item.first.decode('UTF-8')] = item.second.decode('UTF-8')
+        return result
+
+    @extra_attributes.setter
+    def extra_attributes(self, value: Dict[str, str]):
+        """Set additional attributes."""
+        self.c_info.extraAttributes.clear()
+        for key, val in value.items():
+            self.c_info.extraAttributes[key.encode('UTF-8')] = val.encode('UTF-8')
+
+    def as_metadata_item_name(self) -> str:
+        """Convert this IllustrationInfo to a metadata item name.
+
+        Returns:
+            The metadata item name (e.g., "Illustration_48x48@2").
+        """
+        return self.c_info.asMetadataItemName().decode('UTF-8')
+
+    def __repr__(self) -> str:
+        return f"IllustrationInfo(width={self.width}, height={self.height}, scale={self.scale})"
+
+    def __eq__(self, other) -> pybool:
+        if not isinstance(other, IllustrationInfo):
+            return False
+        return (self.width == other.width and
+                self.height == other.height and
+                self.scale == other.scale and
+                self.extra_attributes == other.extra_attributes)
+
+
 cdef class Entry:
     """Entry in a ZIM archive.
 
@@ -1305,9 +1436,18 @@ cdef class Archive:
     def get_illustration_sizes(self) -> Set[pyint]:
         """Sizes for which an illustration is available (@1 scale only).
 
+        .. deprecated:: 3.8.0
+            Use :meth:`get_illustration_infos` instead for full illustration metadata
+            including width, height, and scale information.
+
         Returns:
             The set of available sizes of the illustration.
         """
+        warnings.warn(
+            "get_illustration_sizes() is deprecated, use get_illustration_infos() instead",
+            DeprecationWarning,
+            stacklevel=2
+        )
         return self.c_archive.getIllustrationSizes()
 
     def has_illustration(self, size: pyint = None) -> pybool:
@@ -1320,19 +1460,58 @@ cdef class Archive:
             return self.c_archive.hasIllustration(size)
         return self.c_archive.hasIllustration()
 
-    def get_illustration_item(self, size: pyint = None) -> Item:
+    def get_illustration_item(self, size: pyint = None, info: IllustrationInfo = None) -> Item:
         """Get the illustration Metadata item of the archive.
 
+        Args:
+            size: Optional size of the illustration (for backward compatibility).
+            info: Optional IllustrationInfo with width, height, and scale.
+
         Returns:
             The illustration item.
+
+        Note:
+            Either provide size (int) or info (IllustrationInfo), not both.
+            If neither is provided, returns the default illustration item.
         """
         try:
-            if size is not None:
+            if info is not None:
+                return Item.from_item(move(self.c_archive.getIllustrationItem(info.c_info)))
+            elif size is not None:
                 return Item.from_item(move(self.c_archive.getIllustrationItem(size)))
             return Item.from_item(move(self.c_archive.getIllustrationItem()))
         except RuntimeError as e:
             raise KeyError(str(e))
 
+    def get_illustration_infos(self, width: pyint = None, height: pyint = None,
+                               min_scale: float = None) -> List[IllustrationInfo]:
+        """Get information about available illustrations.
+
+        Args:
+            width: Optional width to filter illustrations (must be provided with height).
+            height: Optional height to filter illustrations (must be provided with width).
+            min_scale: Optional minimum scale to filter illustrations (requires width and height).
+
+        Returns:
+            List of IllustrationInfo objects describing available illustrations.
+
+        Note:
+            - When called without arguments, returns all available illustrations.
+            - When called with width, height, and min_scale, filters illustrations.
+        """
+        cdef zim.IllustrationInfos infos
+        if width is not None and height is not None and min_scale is not None:
+            infos = self.c_archive.getIllustrationInfos(width, height, min_scale)
+        elif width is None and height is None and min_scale is None:
+            infos = self.c_archive.getIllustrationInfos()
+        else:
+            raise ValueError("Either provide all of (width, height, min_scale) or none of them")
+
+        result = []
+        for info in infos:
+            result.append(IllustrationInfo.from_illustration_info(info))
+        return result
+
     @property
     def cluster_cache_max_size(self) -> pyint:
         """Maximum size of the cluster cache.
@@ -1443,6 +1622,7 @@ reader_public_objects = [
     Archive,
     Entry,
     Item,
+    IllustrationInfo,
 ]
 reader = create_module(reader_module_name, reader_module_doc, reader_public_objects)
 

libzim/reader.pyi

@@ -2,6 +2,31 @@ from __future__ import annotations
 
 import pathlib
 from uuid import UUID
+from typing import overload
+
+class IllustrationInfo:
+    def __init__(self, width: int = 0, height: int = 0, scale: float = 1.0) -> None: ...
+    @staticmethod
+    def from_metadata_item_name(name: str) -> IllustrationInfo: ...
+    @property
+    def width(self) -> int: ...
+    @width.setter
+    def width(self, value: int) -> None: ...
+    @property
+    def height(self) -> int: ...
+    @height.setter
+    def height(self, value: int) -> None: ...
+    @property
+    def scale(self) -> float: ...
+    @scale.setter
+    def scale(self, value: float) -> None: ...
+    @property
+    def extra_attributes(self) -> dict[str, str]: ...
+    @extra_attributes.setter
+    def extra_attributes(self, value: dict[str, str]) -> None: ...
+    def as_metadata_item_name(self) -> str: ...
+    def __repr__(self) -> str: ...
+    def __eq__(self, other: object) -> bool: ...
 
 class Item:
     @property
@@ -76,7 +101,14 @@ class Archive:
     def media_count(self) -> int: ...
     def get_illustration_sizes(self) -> set[int]: ...
     def has_illustration(self, size: int | None = None) -> bool: ...
-    def get_illustration_item(self, size: int | None = None) -> Item: ...
+    @overload
+    def get_illustration_item(self, size: int | None = None, info: None = None) -> Item: ...
+    @overload
+    def get_illustration_item(self, size: None = None, info: IllustrationInfo | None = None) -> Item: ...
+    @overload
+    def get_illustration_infos(self) -> list[IllustrationInfo]: ...
+    @overload
+    def get_illustration_infos(self, width: int, height: int, min_scale: float) -> list[IllustrationInfo]: ...
     @property
     def cluster_cache_max_size(self) -> int: ...
     @cluster_cache_max_size.setter