Add support for new illustrations APIs in libzim 9.4.0

CHANGELOG.md

@@ -34,6 +34,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Add a CI job building the documentation on every PR/push so this kind of breakage is caught automatically (#279)
 - Add support for Python 3.15 (#281)
 - Build wheels against the stable ABI (abi3) so a single wheel per platform covers all supported CPython versions (#263)
+- Add `libzim.illustration` module with the `IllustrationInfo` value object, and width/height/scale-aware illustration APIs: `Creator.add_illustration()`/`add_illustration_info()`, `Archive.get_illustration_item()`/`get_illustration_item_info()`, `Archive.get_illustrations_info()` (#232, #233)
 
 ## [3.13.1] - 2026-10-05
 

README.md

@@ -134,7 +134,8 @@ with Creator("test.zim").config_indexing(True, "eng") as creator:
     creator.set_mainpath("home")
     creator.add_item(item)
     creator.add_item(item2)
-    creator.add_illustration(48, illustration)
+    # square illustration at scale 1
+    creator.add_illustration(illustration, 48)
     for name, value in {
         "creator": "python-libzim",
         "description": "Created in python",

libzim/__init__.pyi

@@ -1,4 +1,5 @@
 from libzim import (
+    illustration,  # noqa: F401 # pyright: ignore[reportUnusedImport]
     reader,  # noqa: F401 # pyright: ignore[reportUnusedImport]
     search,  # noqa: F401 # pyright: ignore[reportUnusedImport]
     suggestion,  # noqa: F401 # pyright: ignore[reportUnusedImport]

libzim/illustration.pyi

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import NamedTuple
+
+class IllustrationInfo(NamedTuple):
+    """Information about an illustration in a ZIM archive."""
+
+    width: int = 0
+    height: int = 0
+    scale: float = 1.0
+    extra_attributes: Mapping[str, str] = {}
+    @staticmethod
+    def from_metadata_item_name(name: str) -> IllustrationInfo: ...
+    def as_metadata_item_name(self) -> str: ...

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>
@@ -136,6 +137,8 @@ class Entry : public Wrapper<zim::Entry>
 class Archive : public Wrapper<zim::Archive>
 {
   public:
+    typedef zim::Archive::IllustrationInfos IllustrationInfos;
+
     Archive() = default;
     Archive(const std::string& filename) : Wrapper(zim::Archive(filename)) {};
     Archive(const zim::Archive& o) : Wrapper(o) {};
@@ -147,6 +150,7 @@ class Archive : public Wrapper<zim::Archive>
     FORWARD(wrapper::Entry, getRandomEntry)
     FORWARD(wrapper::Item, getIllustrationItem)
     FORWARD(std::set<unsigned int>, getIllustrationSizes)
+    FORWARD(zim::Archive::IllustrationInfos, getIllustrationInfos)
     std::string getUuid() const
     { auto u = mp_base->getUuid();
       std::string uuids(u.data, u.size());