Make Archive.get_entry_by_id public and deprecate _get_entry_by_id

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- Deprecate `Archive._get_entry_by_id()` in favor of `Archive.get_entry_by_id()` (#225)
+
 ## [3.13.1] - 2026-10-05
 
 ### Changed

libzim/libzim.pyx

@@ -1148,7 +1148,7 @@ cdef class Archive:
         """
         return bytes(self.c_archive.getMetadata(name.encode('UTF-8')))
 
-    def _get_entry_by_id(self, entry_id: pyint) -> Entry:
+    def get_entry_by_id(self, entry_id: pyint) -> Entry:
         """Retrieves an entry by its ID.
 
         Args:
@@ -1160,6 +1160,19 @@ cdef class Archive:
         cdef zim.Entry entry = move(self.c_archive.getEntryByPath(<zim.entry_index_type>entry_id))
         return Entry.from_entry(move(entry))
 
+    def _get_entry_by_id(self, entry_id: pyint) -> Entry:
+        """Retrieves an entry by its ID.
+
+        .. deprecated:: 3.14.0
+            Use :meth:`get_entry_by_id` instead.
+        """
+        warnings.warn(
+            "_get_entry_by_id() is deprecated, use get_entry_by_id() instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.get_entry_by_id(entry_id)
+
     @property
     def has_main_entry(self) -> pybool:
         """Whether Archive has a main entry set.

libzim/reader.pyi

@@ -46,6 +46,7 @@ class Archive:
     def metadata_keys(self) -> list[str]: ...
     def get_metadata_item(self, name: str) -> Item: ...
     def get_metadata(self, name: str) -> bytes: ...
+    def get_entry_by_id(self, entry_id: int) -> Entry: ...
     def _get_entry_by_id(self, entry_id: int) -> Entry: ...
     @property
     def has_main_entry(self) -> bool: ...

tests/test_libzim_reader.py

@@ -325,7 +325,7 @@ def get_content():
     gc.collect()
     # Load a lot of content
     for i in range(0, archive.entry_count, 2):
-        entry = archive._get_entry_by_id(i)
+        entry = archive.get_entry_by_id(i)
         if not entry.is_redirect:
             _ = entry.get_item().content
     # Check everything is ok
@@ -582,8 +582,12 @@ def test_reader_by_id(all_zims, filename):
 
     # test index access
     for index in range(0, zim.entry_count - 1):
-        assert zim._get_entry_by_id(index)._index == index
-        assert zim._get_entry_by_id(index).get_item()._index >= 0
+        assert zim.get_entry_by_id(index)._index == index
+        assert zim.get_entry_by_id(index).get_item()._index >= 0
+
+    if zim.entry_count > 0:
+        with pytest.warns(DeprecationWarning, match=r"_get_entry_by_id\(\) is deprecated"):
+            assert zim._get_entry_by_id(0)._index == 0
 
 
 @skip_if_offline
@@ -642,7 +646,7 @@ def test_cluster_cache(all_zims, filename):
 
     # test index access
     for index in range(0, zim.entry_count - 1):
-        bytes(zim._get_entry_by_id(index).get_item().content)
+        bytes(zim.get_entry_by_id(index).get_item().content)
 
     # check current size is not too big (not really relevant since cache keeps at least
     # one cluster in memory, so this value depends on maximum cluster size
@@ -667,7 +671,7 @@ def test_dirent_cache(all_zims, filename):
 
     # test index access
     for index in range(0, zim.entry_count - 1):
-        bytes(zim._get_entry_by_id(index).get_item().content)
+        bytes(zim.get_entry_by_id(index).get_item().content)
 
     assert zim.dirent_cache_current_size <= new_value
 
@@ -676,7 +680,7 @@ def test_dirent_cache(all_zims, filename):
     assert zim.dirent_cache_current_size == empty_value
 
     for index in range(0, zim.entry_count - 1):
-        bytes(zim._get_entry_by_id(index).get_item().content)
+        bytes(zim.get_entry_by_id(index).get_item().content)
 
     # always at least one entry is kept in cache unless ZIM is empty
     assert zim.dirent_cache_current_size == (1 if zim.entry_count else 0)