Check type stubs against compiled module, fix detected drifts

.github/workflows/QA.yaml

@@ -34,3 +34,9 @@ jobs:
 
       - name: Check pyright
         run: inv check-pyright
+
+      - name: Check stubs with stubtest
+        run: inv check-stubtest
+
+      - name: Check stubs annotations
+        run: inv check-stub-annotations

libzim/__init__.pyi

@@ -1,8 +1,10 @@
 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]
-    version,  # noqa: F401 # pyright: ignore[reportUnusedImport]
-    writer,  # noqa: F401 # pyright: ignore[reportUnusedImport]
+    illustration,  # pyright: ignore[reportUnusedImport]
+    reader,  # pyright: ignore[reportUnusedImport]
+    search,  # pyright: ignore[reportUnusedImport]
+    suggestion,  # pyright: ignore[reportUnusedImport]
+    version,  # pyright: ignore[reportUnusedImport]
+    writer,  # pyright: ignore[reportUnusedImport]
 )
+
+__all__ = ["illustration", "reader", "search", "suggestion", "version", "writer"]

libzim/illustration.pyi

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

libzim/libzim.pyx

@@ -45,7 +45,7 @@ from collections import OrderedDict
 from collections import namedtuple as _namedtuple
 from collections.abc import Generator, Iterator, Mapping
 from types import MappingProxyType, ModuleType
-from typing import TextIO
+from typing import Self, TextIO
 from uuid import UUID
 
 from cpython.buffer cimport PyBUF_WRITABLE
@@ -69,12 +69,12 @@ def create_module(name, doc, members):
     _all = []
     for obj in members:
         if isinstance(obj, tuple):
-            name = obj[0]
+            member_name = obj[0]
             obj = obj[1]
         else:
-            name = obj.__name__
-        setattr(module, name, obj)
-        _all.append(name)
+            member_name = obj.__name__
+        setattr(module, member_name, obj)
+        _all.append(member_name)
     module.__all__ = _all
     sys.modules[name] = module
     return module
@@ -392,7 +392,7 @@ cdef class _Creator:
     def __init__(self, filename: pathlib.Path):
         pass
 
-    def config_verbose(self, bool verbose: bool) -> _Creator:
+    def config_verbose(self, bool verbose: bool) -> Self:
         """Set creator verbosity inside libzim (default: off).
 
         Args:
@@ -406,7 +406,7 @@ cdef class _Creator:
         self.c_creator.configVerbose(verbose)
         return self
 
-    def config_compression(self, compression: Compression) -> _Creator:
+    def config_compression(self, compression: Compression) -> Self:
         """Set compression algorithm to use.
 
         Check libzim for default setting. (Fall 2021 default: zstd).
@@ -422,7 +422,7 @@ cdef class _Creator:
         self.c_creator.configCompression(zim.comp_from_int(compression.value))
         return self
 
-    def config_clustersize(self, int size: pyint) -> _Creator:
+    def config_clustersize(self, int size: pyint) -> Self:
         """Set size of created clusters.
 
         Check libzim for default setting. (Fall 2021 default: 2Mib).
@@ -441,7 +441,7 @@ cdef class _Creator:
         self.c_creator.configClusterSize(size)
         return self
 
-    def config_indexing(self, bool indexing: bool, str language: str) -> _Creator:
+    def config_indexing(self, bool indexing: bool, str language: str) -> Self:
         """Configures the full-text indexing feature.
 
         Args:
@@ -456,7 +456,7 @@ cdef class _Creator:
         self.c_creator.configIndexing(indexing, language.encode('UTF-8'))
         return self
 
-    def config_nbworkers(self, int nb_workers: pyint) -> _Creator:
+    def config_nbworkers(self, int nb_workers: pyint) -> Self:
         """Configures the number of threads to use for internal workers (default: 4).
 
         Args:
@@ -470,7 +470,7 @@ cdef class _Creator:
         self.c_creator.configNbWorkers(nb_workers)
         return self
 
-    def set_mainpath(self, str main_path: str) -> _Creator:
+    def set_mainpath(self, str main_path: str) -> Self:
         """Set path of the main entry.
 
         Args:
@@ -486,7 +486,7 @@ cdef class _Creator:
         self,
         content: bytes,
         width: pyint,
-        height: pyint = None,
+        height: pyint | None = None,
         scale: float = 1.0,
     ):
         """Add a PNG illustration to Archive.
@@ -540,7 +540,7 @@ cdef class _Creator:
         cdef zim.IllustrationInfo c_ii = _illustration_info_to_c(info)
         self.c_creator.addIllustration(c_ii, _content)
 
-#    def set_uuid(self, uuid) -> _Creator:
+#    def set_uuid(self, uuid) -> Self:
 #        self.c_creator.setUuid(uuid)
 
     def add_item(self, writer_item not None: BaseWritingItem):
@@ -1477,7 +1477,7 @@ cdef class Archive:
         )
         return self.c_archive.getIllustrationSizes()
 
-    def has_illustration(self, size: pyint = None) -> pybool:
+    def has_illustration(self, size: pyint | None = None) -> pybool:
         """Whether Archive has an illustration metadata for this size.
 
         Returns:
@@ -1489,9 +1489,9 @@ cdef class Archive:
 
     def get_illustration_item(
         self,
-        width: pyint = None,
-        height: pyint = None,
-        scale: float = None,
+        width: pyint | None = None,
+        height: pyint | None = None,
+        scale: float | None = None,
     ) -> Item:
         """Get the illustration Metadata item of the archive.
 
@@ -1556,8 +1556,8 @@ cdef class Archive:
         except RuntimeError as e:
             raise KeyError(str(e))
 
-    def get_illustrations_info(self, width: pyint = None, height: pyint = None,
-                               min_scale: float = None) -> list[IllustrationInfo]:
+    def get_illustrations_info(self, width: pyint | None = None, height: pyint | None = None,
+                               min_scale: float | None = None) -> list[IllustrationInfo]:
         """Get information about available illustrations.
 
         Args:
@@ -1978,7 +1978,9 @@ for path in suggestion.get_results(10, 10) # get result from 10 to 20 (10 result
     print(path, archive.get_entry_by_path(path).title)
 ```"""
 suggestion_public_objects = [
-    SuggestionSearcher
+    SuggestionResultSet,
+    SuggestionSearch,
+    SuggestionSearcher,
 ]
 suggestion = create_module(suggestion_module_name, suggestion_module_doc, suggestion_public_objects)
 

libzim/reader.pyi

@@ -3,8 +3,20 @@ from __future__ import annotations
 import pathlib
 from uuid import UUID
 
+from typing_extensions import disjoint_base
+
 from libzim.illustration import IllustrationInfo
 
+__all__ = [
+    "Archive",
+    "Entry",
+    "Item",
+    "get_cluster_cache_current_size",
+    "get_cluster_cache_max_size",
+    "set_cluster_cache_max_size",
+]
+
+@disjoint_base
 class Item:
     @property
     def title(self) -> str: ...
@@ -20,6 +32,7 @@ class Item:
     def size(self) -> int: ...
     def __repr__(self) -> str: ...
 
+@disjoint_base
 class Entry:
     @property
     def title(self) -> str: ...
@@ -33,6 +46,7 @@ class Entry:
     def get_item(self) -> Item: ...
     def __repr__(self) -> str: ...
 
+@disjoint_base
 class Archive:
     def __init__(self, filename: pathlib.Path) -> None: ...
     @property
@@ -100,5 +114,5 @@ class Archive:
     def __repr__(self) -> str: ...
 
 def get_cluster_cache_max_size() -> int: ...
-def set_cluster_cache_max_size(nb_clusters: int): ...
+def set_cluster_cache_max_size(size_in_bytes: int): ...
 def get_cluster_cache_current_size() -> int: ...

libzim/search.pyi

@@ -3,11 +3,17 @@ from __future__ import annotations
 from collections.abc import Iterator
 from typing import Self
 
+from typing_extensions import disjoint_base
+
 from libzim.reader import Archive
 
+__all__ = ["Query", "Search", "SearchResult", "SearchResultSet", "Searcher"]
+
+@disjoint_base
 class Query:
     def set_query(self, query: str) -> Self: ...
 
+@disjoint_base
 class SearchResult:
     archive: Archive
     path: str
@@ -17,13 +23,16 @@ class SearchResult:
         self, archive: Archive, path: str, title: str, snippet: str
     ) -> None: ...
 
+@disjoint_base
 class SearchResultSet:
     def __iter__(self) -> Iterator[SearchResult]: ...
 
+@disjoint_base
 class Search:
     def get_estimated_matches(self) -> int: ...
     def get_results(self, start: int, count: int) -> SearchResultSet: ...
 
+@disjoint_base
 class Searcher:
     def __init__(
         self,

libzim/suggestion.pyi

@@ -2,15 +2,22 @@ from __future__ import annotations
 
 from collections.abc import Iterator
 
+from typing_extensions import disjoint_base
+
 from libzim.reader import Archive
 
+__all__ = ["SuggestionResultSet", "SuggestionSearch", "SuggestionSearcher"]
+
+@disjoint_base
 class SuggestionResultSet:
     def __iter__(self) -> Iterator[str]: ...
 
+@disjoint_base
 class SuggestionSearch:
     def get_estimated_matches(self) -> int: ...
     def get_results(self, start: int, count: int) -> SuggestionResultSet: ...
 
+@disjoint_base
 class SuggestionSearcher:
     def __init__(self, archive: Archive) -> None: ...
     def suggest(self, query: str) -> SuggestionSearch: ...

libzim/version.pyi

@@ -4,6 +4,8 @@ import sys
 from collections import OrderedDict
 from typing import TextIO
 
+__all__ = ["get_libzim_version", "get_versions", "print_versions"]
+
 def print_versions(out: TextIO = sys.stdout) -> None: ...
 def get_versions() -> OrderedDict[str, str]: ...
 def get_libzim_version() -> str: ...

libzim/writer.pyi

@@ -6,16 +6,31 @@ import types
 from collections.abc import Callable, Generator
 from typing import Self
 
+from typing_extensions import disjoint_base
+
 from libzim.illustration import IllustrationInfo
 
+__all__ = [
+    "Blob",
+    "Compression",
+    "ContentProvider",
+    "Creator",
+    "FileProvider",
+    "Hint",
+    "IndexData",
+    "Item",
+    "StringProvider",
+]
+
 class Compression(enum.Enum):
-    none: Self
-    zstd: Self
+    none = ...
+    zstd = ...
 
 class Hint(enum.Enum):
-    COMPRESS: Self
-    FRONT_ARTICLE: Self
+    COMPRESS = ...
+    FRONT_ARTICLE = ...
 
+@disjoint_base
 class Blob:
     def __init__(self, content: str | bytes) -> None: ...
     def size(self) -> int: ...

pyproject.toml

@@ -56,6 +56,7 @@ lint = [
 ]
 check = [
   "pyright==1.1.414",
+  "mypy==2.4.0",
   "libzim",
   "libzim[build]",
   "libzim[test]",
@@ -331,7 +332,7 @@ exclude_lines = [
 ]
 
 [tool.pyright]
-include = ["libzim", "tests", "tasks.py"]
+include = ["libzim", "tests", "tasks.py", "scripts"]
 exclude = [".env/**", ".venv/**"]
 pythonVersion = "3.15"
 typeCheckingMode="basic"