Skip to content

libzim.writer

libzim writer module

  • Creator to create ZIM files
  • Item to store ZIM articles metadata
  • ContentProvider to store an Item's content
  • Blob to store actual content
  • StringProvider to store an Item's content from a string
  • FileProvider to store an Item's content from a file path
  • Compression to select the algorithm to compress ZIM archive with

Usage:

with Creator(pathlib.Path("myfile.zim")) as creator:
    creator.config_verbose(False)
    creator.add_metadata("Name", b"my name")
    # example
    creator.add_item(MyItemSubclass(path, title, mimetype, content)
    creator.set_mainpath(path)

Classes:

  • Blob –

    A writable blob of data.

  • Compression –

    Compression algorithms available to create ZIM files.

  • ContentProvider –

    ABC in charge of providing the content to add in the archive to the Creator.

  • Creator –

    Creator to create ZIM files.

  • FileProvider –

    ContentProvider for a file using its local path.

  • Hint –

    Generic way to pass information to the creator on how to handle item/redirection.

  • IndexData –

    IndexData stub to override.

  • Item –

    Data to be added to the archive.

  • StringProvider –

    ContentProvider for a single encoded-or-not UTF-8 string.

Blob

A writable blob of data.

Attributes:

  • c_blob (Blob) –

    A pointer to a C++ Blob object.

  • ref_content (bytes) –

    A reference to the content stored in the blob.

Methods:

  • size –

    The size (in bytes) of the blob's content.

size method descriptor 

size() -> int

The size (in bytes) of the blob's content.

Returns:

  • int –

    The size of the blob (in bytes).

Compression

Bases: enum.Enum

Compression algorithms available to create ZIM files.

Attributes:

  • none –

    Compression algorithms available to create ZIM files.

  • zstd –

    Compression algorithms available to create ZIM files.

none class-attribute 

none = <Compression.none: 0>

Compression algorithms available to create ZIM files.

zstd class-attribute 

zstd = <Compression.zstd: 1>

Compression algorithms available to create ZIM files.

ContentProvider

ABC in charge of providing the content to add in the archive to the Creator.

Creator

Bases: libzim._Creator

Creator to create ZIM files.

Methods:

Attributes:

  • filename –

    Path of the ZIM Archive on the filesystem.

filename property 

filename

Path of the ZIM Archive on the filesystem.

Returns:

  • Path –

    Path of the ZIM Archive on the filesystem.

add_alias method descriptor 

add_alias(
    path: str,
    title: str,
    targetPath: str,
    hints: Dict[Hint, int],
)

Alias the (existing) entry targetPath as a new entry path.

Parameters:

  • path (str) –

    The path for the new alias.

  • title (str) –

    The title associated with the alias.

  • targetPath (str) –

    The existing entry to be aliased.

  • hints (dict[Hint, int]) –

    A dictionary of hints for the alias.

Raises:

add_illustration method descriptor 

add_illustration(size: int, content: bytes)

Add a PNG illustration to Archive.

Refer to https://wiki.openzim.org/wiki/Metadata for more details.

Parameters:

  • size (int) –

    The width of the square PNG illustration in pixels.

  • content (bytes) –

    The binary content of the PNG illustration.

Raises:

  • RuntimeError –

    If an illustration with the same width already exists.

add_item method descriptor 

add_item(writer_item: BaseWritingItem)

Add an item to the Creator object.

Parameters:

  • item (WriterItem) –

    The item to add to the archive.

Raises:

  • RuntimeError –

    If an item with the same path already exists.

  • RuntimeError –

    If the ZimCreator has already been finalized.

add_redirection method descriptor 

add_redirection(
    path: str,
    title: str,
    targetPath: str,
    hints: Dict[Hint, int],
)

Add redirection entry to the archive.

Refer to https://wiki.openzim.org/wiki/ZIM_file_format#Redirect_Entry for more details.

Parameters:

  • path (str) –

    The path of the redirection entry.

  • title (str) –

    The title associated with the redirection.

  • targetPath (str) –

    The target path for the redirection.

  • hints (dict[Hint, int]) –

    A dictionary of hints for the redirection.

Raises:

  • RuntimeError –

    If a redirection entry exists with the same path.

config_clustersize method descriptor 

config_clustersize(size: int) -> _Creator

Set size of created clusters.

Check libzim for default setting. (Fall 2021 default: 2Mib).

libzim will store at most this value per cluster before creating another one.

Parameters:

  • size (int) –

    The maximum size (in bytes) for each cluster.

Returns:

  • _Creator –

    The Creator instance with updated cluster size settings.

config_indexing method descriptor 

config_indexing(indexing: bool, language: str) -> _Creator

Configures the full-text indexing feature.

Parameters:

  • indexing (bool) –

    whether to create a full-text index of the content

  • language (str) –

    language (ISO-639-3 code) to assume content in during indexation.

Returns:

  • _Creator –

    The Creator instance with updated indexing settings.

config_nbworkers method descriptor 

config_nbworkers(nbWorkers: int) -> _Creator

Configures the number of threads to use for internal workers (default: 4).

Parameters:

  • nbWorkers (int) –

    The number of threads to allocate.

Returns:

  • _Creator –

    The Creator instance with updated worker thread settings.

config_verbose method descriptor 

config_verbose(verbose: bool) -> _Creator

Set creator verbosity inside libzim (default: off).

Parameters:

  • verbose (bool) –

    Whether to enable verbosity.

Returns:

  • _Creator –

    The Creator instance with updated verbosity settings.

set_mainpath method descriptor 

set_mainpath(mainPath: str) -> _Creator

Set path of the main entry.

Parameters:

  • mainPath (str) –

    The path of the main entry.

Returns:

  • _Creator –

    The Creator instance with the updated main entry path.

FileProvider

Bases: libzim.writer.ContentProvider

ContentProvider for a file using its local path.

Hint

Bases: enum.Enum

Generic way to pass information to the creator on how to handle item/redirection.

Attributes:

  • COMPRESS –

    Generic way to pass information to the creator on how to handle item/redirection.

  • FRONT_ARTICLE –

    Generic way to pass information to the creator on how to handle item/redirection.

COMPRESS class-attribute 

COMPRESS = <Hint.COMPRESS: 0>

Generic way to pass information to the creator on how to handle item/redirection.

FRONT_ARTICLE class-attribute 

FRONT_ARTICLE = <Hint.FRONT_ARTICLE: 1>

Generic way to pass information to the creator on how to handle item/redirection.

IndexData

IndexData stub to override.

A subclass of it should be returned in Item.get_indexdata().

Item

Data to be added to the archive.

This is a stub to override. Pass a subclass of it to Creator.add_item()

StringProvider

Bases: libzim.writer.ContentProvider

ContentProvider for a single encoded-or-not UTF-8 string.