Skip to content

libzim.reader

libzim reader module

  • Archive to open and read ZIM files (gives access to all Entry)
  • Entry knows about redirections, exposes path and title and gives access to Item
  • Item holds the content and metadata

Usage:

with Archive(fpath) as zim:
    entry = zim.get_entry_by_path(zim.main_entry.path)
    print(f"Article {entry.title} at {entry.path} is "
          f"{entry.get_item().content.nbytes}b")

Classes:

  • Archive –

    ZIM Archive Reader

  • Entry –

    Entry in a ZIM archive.

  • Item –

    Item in a ZIM archive

Functions:

Archive

ZIM Archive Reader

Parameters:

  • filename (Path) –

    Full path to a zim file.

Methods:

Attributes:

all_entry_count property 

all_entry_count

Number of entries in Archive.

Total number of entries in the archive, including internal entries created by libzim itself, metadata, indexes, etc.

Returns:

  • int –

    Number of entries in Archive.

article_count property 

article_count

Number of “articles” in the Archive.

If Archive has_new_namespace_scheme then this is the number of Entry with “FRONT_ARTICLE” Hint.

Otherwise, this is the number or entries in “A” namespace.

Note: a few ZIM created during transition might have new scheme but no listing, resulting in this returning all entries.

Returns:

  • int –

    Number of “articles” in the Archive.

checksum property 

checksum

The checksum stored in the archive.

Returns:

  • str –

    The checksum stored in the archive.

dirent_cache_current_size property 

dirent_cache_current_size

Size of the dirent cache.

Returns:

  • int –

    number of dirents currently stored in the cache.

dirent_cache_max_size property 

dirent_cache_max_size

Maximum size of the dirent cache.

Returns:

  • int –

    maximum number of dirents stored in the cache.

entry_count property 

entry_count

Number of user entries in Archive.

If Archive doesn't support “user entries” then this returns all_entry_count.

Returns:

  • int –

    Number of user entries in Archive.

filename property 

filename

Path of the ZIM Archive on the filesystem.

Returns:

  • Path –

    Path of the ZIM Archive on the filesystem.

filesize property 

filesize

Total size of ZIM file (or sum of files if split).

Returns:

  • int –

    Total size of ZIM file (or sum of files if split).

has_checksum property 

has_checksum

Whether Archive includes a checksum of its content.

The checksum is not the checksum of the file. It is an internal checksum stored in the zim file.

Returns:

  • bool –

    Whether Archive includes a checksum of its content.

has_fulltext_index property 

has_fulltext_index

Whether Archive includes a full-text index.

Returns:

  • bool –

    Whether Archive includes a full-text index.

has_main_entry property 

has_main_entry

Whether Archive has a main entry set.

Returns:

  • bool –

    Whether Archive has a main entry set.

has_new_namespace_scheme property 

has_new_namespace_scheme

Whether Archive is using new “namespaceless” namespace scheme.

Returns:

  • bool –

    Whether Archive is using new “namespaceless” namespace scheme.

has_title_index property 

has_title_index

Whether Archive includes a title index.

Returns:

  • bool –

    Whether Archive includes a title index.

is_multipart property 

is_multipart

Whether Archive is multipart (split over multiple files).

Returns:

  • bool –

    Whether Archive is multipart (split over multiple files).

main_entry property 

main_entry

The main entry of the Archive.

Returns:

  • Entry –

    The main entry of the Archive.

media_count property 

media_count

Number of media in the Archive.

Returns:

  • int –

    Number of media in the Archive.

metadata_keys property 

metadata_keys

List of Metadata keys present in this archive.

Returns:

  • list[str] –

    List of Metadata keys present in this archive.

uuid property 

uuid

The uuid of the archive.

Returns:

  • UUID –

    The uuid of the archive.

check method descriptor 

check() -> bool

Whether Archive has a checksum and file verifies it.

Returns:

  • bool –

    True if the file is valid, otherwise False.

get_entry_by_path method descriptor 

get_entry_by_path(path: str) -> Entry

Retrieves an Entry by its path.

Parameters:

  • path –

    The path of the article.

Returns:

  • Entry –

    The Entry object corresponding to the given path.

Raises:

  • KeyError –

    If an entry with the provided path is not found in the archive

get_entry_by_title method descriptor 

get_entry_by_title(title: str) -> Entry

Fetches an entry by title.

If ZIM doesn't contain a listing/titleOrdered/v1 entry (most likely because if was created without any FRONT_ARTICLE) then this yields results for matching path if the title was not set at creation time.

Parameters:

  • title (str) –

    The article title.

Returns:

  • Entry –

    The first Entry object matching the title.

Raises:

  • KeyError –

    If no entry with the provided title is found.

get_illustration_item method descriptor 

get_illustration_item(size: int = None) -> Item

Get the illustration Metadata item of the archive.

Returns:

  • Item –

    The illustration item.

get_illustration_sizes method descriptor 

get_illustration_sizes() -> Set[int]

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:

  • Set[int] –

    The set of available sizes of the illustration.

get_metadata method descriptor 

get_metadata(name: str) -> bytes

Retrieves the content of a metadata entry.

Parameters:

  • name (str) –

    The name or path of the metadata entry.

Returns:

  • bytes –

    The content of the metadata entry, which can be of any type.

get_metadata_item method descriptor 

get_metadata_item(name: str) -> Item

Get a Metadata's Item by name.

Parameters:

  • name (str) –

    The name of the metadata item.

Returns:

  • Item –

    The metadata item corresponding to the given name.

get_random_entry method descriptor 

get_random_entry() -> Entry

Get a random Entry.

Returns:

  • Entry –

    A random entry.

Raises:

  • KeyError –

    If no valid random entry is found.

has_entry_by_path method descriptor 

has_entry_by_path(path: str) -> bool

Whether Archive has an entry with this path.

Returns:

  • bool –

    True if the archive has entry with this path, otherwise False.

has_entry_by_title method descriptor 

has_entry_by_title(title: str) -> bool

Checks if the archive contains an entry with the specified title.

This method relies on get_entry_by_title(), so its behavior applies here.

Parameters:

  • title (str) –

    The title of the entry.

Returns:

  • bool –

    True if an entry with the title exists, otherwise False.

has_illustration method descriptor 

has_illustration(size: int = None) -> bool

Whether Archive has an illustration metadata for this size.

Returns:

  • bool –

    True if the archive has an illustration metadata, otherwise False.

Entry

Entry in a ZIM archive.

Attributes:

  • *c_entry (Entry) –

    a pointer to the C++ entry object.

Methods:

is_redirect property 

is_redirect

Whether entry is a redirect.

Returns:

  • bool –

    Whether entry is a redirect.

path property 

path

The UTF-8 decoded path of the entry.

Returns:

  • str –

    The UTF-8 decoded path of the entry.

title property 

title

The UTF-8 decoded title of the entry.

Returns:

  • str –

    The UTF-8 decoded title of the entry.

get_item method descriptor 

get_item() -> Item

Get the Item associated with this entry.

Returns:

  • Item –

    The item associated with this entry.

get_redirect_entry method descriptor 

get_redirect_entry() -> Entry

Get the target entry if this entry is a redirect.

Returns:

  • Entry –

    The target entry of the redirect.

Item

Item in a ZIM archive

Attributes:

*c_item (zim.Item): a pointer to the C++ Item object.

Attributes:

  • content –

    The data associated to the item.

  • mimetype –

    The mimetype of the item.

  • path –

    The UTF-8 decoded path of the item.

  • size –

    The size (in bytes) of the item.

  • title –

    The UTF-8 decoded title of the item.

content property 

content

The data associated to the item.

Returns:

mimetype property 

mimetype

The mimetype of the item.

Returns:

  • str –

    The mimetype of the item.

path property 

path

The UTF-8 decoded path of the item.

Returns:

  • str –

    The UTF-8 decoded path of the item.

size property 

size

The size (in bytes) of the item.

Returns:

  • int –

    The size (in bytes) of the item.

title property 

title

The UTF-8 decoded title of the item.

Returns:

  • str –

    The UTF-8 decoded title of the item.

get_cluster_cache_current_size method descriptor 

get_cluster_cache_current_size() -> int

Get the current size of the cluster cache.

Returns:

  • int –

    the current memory size (in bytes) used by the cluster cache.

get_cluster_cache_max_size method descriptor 

get_cluster_cache_max_size() -> int

Get the maximum size of the cluster cache.

Returns:

  • int –

    the maximum memory size used by the cluster cache (in bytes).

set_cluster_cache_max_size method descriptor 

set_cluster_cache_max_size(size_in_bytes: int)

Set the size of the cluster cache.

If the new size is lower than the number of currently stored clusters some clusters will be dropped from cache to respect the new size.

Parameters:

  • size_in_bytes (int) –

    the memory limit (in bytes) for the cluster cache.