Merge pull request #97 from FledgeXu/config

rgaudin · web-flow · commit dcb07b379612 · 2023-03-16T13:13:14.000Z
Introduce `config_metadata`
diff --git a/src/zimscraperlib/constants.py b/src/zimscraperlib/constants.py
@@ -2,6 +2,7 @@
 # -*- coding: utf-8 -*-
 # vim: ai ts=4 sts=4 et sw=4 nu
 
+import base64
 import pathlib
 
 ROOT_DIR = pathlib.Path(__file__).parent
@@ -17,3 +18,30 @@
 
 # list of mimetypes we consider articles using it should default to FRONT_ARTICLE
 FRONT_ARTICLE_MIMETYPES = ["text/html"]
+
+# list of mandatory meta tags of the zim file.
+MANDATORY_ZIM_METADATA_KEYS = [
+    "Name",
+    "Title",
+    "Creator",
+    "Publisher",
+    "Date",
+    "Description",
+    "Language",
+    "Illustration_48x48@1",
+]
+
+DEFAULT_DEV_ZIM_METADATA = {
+    "Name": "Test Name",
+    "Title": "Test Title",
+    "Creator": "Test Creator",
+    "Publisher": "Test Publisher",
+    "Date": "2023-01-01",
+    "Description": "Test Description",
+    "Language": "fra",
+    "Illustration_48x48_at_1": base64.b64decode(
+        "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAAGXRFWHRTb2Z0d2FyZQBB"
+        "ZG9iZSBJbWFnZVJlYWR5ccllPAAAAA9JREFUeNpi+P//P0CAAQAF/gL+Lc6J7gAAAABJ"
+        "RU5ErkJggg=="
+    ),
+}
diff --git a/src/zimscraperlib/zim/creator.py b/src/zimscraperlib/zim/creator.py
@@ -22,11 +22,15 @@
 import pathlib
 import re
 import weakref
-from typing import Any, Callable, Dict, List, Optional, Tuple, Union
+from typing import Any, Callable, Iterable, Optional, Tuple, Union
 
 import libzim.writer
 
-from ..constants import FRONT_ARTICLE_MIMETYPES
+from ..constants import (
+    DEFAULT_DEV_ZIM_METADATA,
+    FRONT_ARTICLE_MIMETYPES,
+    MANDATORY_ZIM_METADATA_KEYS,
+)
 from ..filesystem import delete_callback, get_content_mimetype, get_file_mimetype
 from ..types import get_mime_for_name
 from .items import StaticItem
@@ -80,28 +84,16 @@ class Creator(libzim.writer.Creator):
     def __init__(
         self,
         filename: pathlib.Path,
-        main_path: str = None,
-        language: Optional[Union[str, List[str]]] = "eng",
+        main_path: str,
         compression: Optional[str] = None,
         workaround_nocancel: Optional[bool] = True,
         ignore_duplicates: Optional[bool] = False,
-        **metadata: Dict[str, Union[str, datetime.date, datetime.datetime]]
     ):
         super().__init__(filename=filename)
+        self._metadata = dict()
         self.can_finish = True
 
-        if main_path:
-            self.main_path = main_path
-
-        if language:
-            if not isinstance(language, list):
-                language = language.split(",")
-            self.config_indexing(True, language[0])
-            ld = {"Language": ",".join(language)}
-            if metadata:
-                metadata.update(ld)
-            else:
-                metadata = ld
+        self.set_mainpath(main_path)
 
         if compression:
             self.config_compression(
@@ -110,26 +102,108 @@ def __init__(
                 else compression
             )
 
-        if metadata:
-            self.metadata = metadata
-
         self.workaround_nocancel = workaround_nocancel
         self.ignore_duplicates = ignore_duplicates
 
     def start(self):
+        if not all(
+            [
+                key in self._metadata.keys() and self._metadata.get(key, None)
+                for key in MANDATORY_ZIM_METADATA_KEYS
+            ]
+        ):
+            raise ValueError("Mandatory metadata are not all set.")
+
+        for name, value in self._metadata.items():
+            if value:
+                self._validate_metadata(name, value)
+
         super().__enter__()
 
-        if getattr(self, "main_path", None):
-            self.set_mainpath(self.main_path)
+        self.add_illustration(48, self._metadata["Illustration_48x48@1"])
+        del self._metadata["Illustration_48x48@1"]
+        for name, value in self._metadata.items():
+            if value:
+                self.add_metadata(name, value)
 
-        if getattr(self, "metadata", None):
-            self.update_metadata(**self.metadata)
         return self
 
-    def update_metadata(self, **kwargs):
-        if kwargs:
-            for name, value in kwargs.items():
-                self.add_metadata(name, value)
+    def _validate_metadata(self, name, value):
+        if name == "Counter":
+            raise ValueError("You do not need to set Counter.")
+
+        if name == "Description" and len(value) > 80:
+            raise ValueError("Description is too long.")
+
+        if name == "LongDescription" and len(value) > 4000:
+            raise ValueError("LongDescription is too long.")
+
+    def config_metadata(
+        self,
+        *,
+        Name: str,
+        Language: str,
+        Title: str,
+        Description: str,
+        LongDescription: Optional[str] = None,
+        Creator: str,
+        Publisher: str,
+        Date: Union[datetime.datetime, datetime.date, str],
+        Illustration_48x48_at_1: bytes,
+        Tags: Optional[Union[Iterable[str], str]] = None,
+        Scraper: Optional[str] = None,
+        Flavour: Optional[str] = None,
+        Source: Optional[str] = None,
+        License: Optional[str] = None,
+        Relation: Optional[str] = None,
+        **extras: str,
+    ):
+        """
+        A chaining functions which configures the metadata of the Creator class.
+        You must set all mandatory metadata in this phase.
+
+        Parameters:
+            check out: https://wiki.openzim.org/wiki/Metadata
+            all the extra metadata must be plain text.
+
+        Returns:
+            Self
+        """
+        self._metadata.update(
+            {
+                "Name": Name,
+                "Title": Title,
+                "Creator": Creator,
+                "Publisher": Publisher,
+                "Date": Date,
+                "Description": Description,
+                "Language": Language,
+                "License": License,
+                "LongDescription": LongDescription,
+                "Tags": Tags,
+                "Relation": Relation,
+                "Flavour": Flavour,
+                "Source": Source,
+                "Scraper": Scraper,
+                "Illustration_48x48@1": Illustration_48x48_at_1,
+            }
+        )
+        self._metadata.update(extras)
+        language = self._metadata.get("Language", "").split(",")
+        self.config_indexing(True, language[0])
+
+        return self
+
+    def config_dev_metadata(self, **extras: str):
+        """
+        A Test function. It will set the default test metadata for a Creator instance.
+
+        Returns:
+            Self
+        """
+        devel_default_metadata = DEFAULT_DEV_ZIM_METADATA.copy()
+        devel_default_metadata.update(extras)
+        return self.config_metadata(**devel_default_metadata)
 
     def add_item_for(
         self,
@@ -254,9 +328,6 @@ def add_redirect(
                 self.can_finish = False  # pragma: no cover
             raise
 
-    def add_default_illustration(self, content: bytes):
-        self.add_illustration(48, content)
-
     def finish(self, exc_type=None, exc_val=None, exc_tb=None):
         """Triggers finalization of ZIM creation and create final ZIM file."""
         if not getattr(self, "can_finish", False):
diff --git a/src/zimscraperlib/zim/filesystem.py b/src/zimscraperlib/zim/filesystem.py
@@ -125,6 +125,7 @@ def make_zim_file(
     source: str = None,
     flavour: str = None,
     scraper: str = None,
+    long_description: str = None,
     without_fulltext_index: bool = False,
     redirects: Sequence[Tuple[str, str, str]] = None,
     redirects_file: pathlib.Path = None,
@@ -149,39 +150,37 @@ def make_zim_file(
     if not favicon_path.exists() or not favicon_path.is_file():
         raise IOError(f"Incorrect favicon: {favicon} ({favicon_path})")
 
-    zim_file = Creator(
-        filename=fpath,
-        main_path=main_page,
-        index_language="" if without_fulltext_index else language,
+    with open(favicon_path, "rb") as fh:
+        favicon_data = fh.read()
+
+    zim_file = Creator(filename=fpath, main_path=main_page).config_metadata(
         **{
             k: v
             for k, v in {
                 # (somewhat) mandatory
-                "name": name,
-                "title": title,
-                "description": description,
-                "date": date or datetime.date.today(),
-                "language": language,
-                "creator": creator,
-                "publisher": publisher,
+                "Name": name,
+                "Title": title,
+                "Description": description,
+                "Date": date or datetime.date.today(),
+                "Language": language,
+                "Creator": creator,
+                "Publisher": publisher,
                 # optional
-                "tags": ";".join(tags) if tags else None,
-                "source": source,
-                "flavour": flavour,
-                "scraper": scraper,
+                "Tags": ";".join(tags) if tags else None,
+                "Source": source,
+                "Flavour": flavour,
+                "Scraper": scraper,
+                "LongDescription": long_description,
+                "Illustration_48x48_at_1": favicon_data,
             }.items()
             if v is not None
-        },
+        }
     )
 
     zim_file.start()
     try:
         logger.debug(f"Preparing zimfile at {zim_file.filename}")
 
-        # add favicon as illustration
-        with open(favicon_path, "rb") as fh:
-            zim_file.add_default_illustration(fh.read())
-
         # recursively add content from build_dir
         logger.debug(f"Recursively adding files from {build_dir}")
         add_to_zim(build_dir, zim_file, build_dir)
diff --git a/tests/zim/test_zim_creator.py b/tests/zim/test_zim_creator.py
