Cleaner writer API

- fixed, added or updated docstrings
- added type annotations to ease self-discovery
- made `mandatory_metadata_ok` a property
- added a `_closed` boolean prop in creator to record finalization status
- fixed the deletion issue after a contextmanager auto-close (using `self._closed`)
- simplify public API by moving single-use method:
 - `_get_counter_string()` and `write_metadata()` to `close()`
 - `_update_article_counter()` to `add_article()`
 - `pascalize()` to `update_metadata()`
- `write_metadata()` to autmatically convert Date from datetime.datetime as well

Author: renaud gaudin

libzim/writer.py

@@ -1,3 +1,16 @@
+""" libzim writer module
+    - Creator to create ZIM files
+    - Article to store ZIM articles metadata
+    - Blob to store ZIM article content
+    Usage:
+    with Creator(pathlib.Path("myfile.zim"), main_page="welcome.html") as xf:
+        article = MyArticleSubclass(
+            url="A/welcome.html",
+            title="My Title",
+            content=Blob("My content"))
+        zf.add_article(article)
+        zf.update_metadata(tags="new;demo") """
+
 # This file is part of python-libzim
 # (see https://github.com/libzim/python-libzim)
 #
@@ -19,7 +32,7 @@
 
 import pathlib
 import datetime
-from collections import defaultdict
+import collections
 
 from .wrapper import Creator as _Creator
 from .wrapper import WritingBlob as Blob
@@ -28,113 +41,132 @@
 
 
 class Article:
+    """ Article stub to override
+
+        Pass a subclass of it to Creator.add_article() """
+
     def __init__(self):
         self._blob = None
 
-    def get_url(self):
+    def get_url(self) -> str:
+        """ Full URL of article including namespace """
         raise NotImplementedError
 
-    def get_title(self):
+    def get_title(self) -> str:
+        """ Article title. Might be indexed and used in suggestions """
         raise NotImplementedError
 
-    def is_redirect(self):
+    def is_redirect(self) -> bool:
+        """ Whether this redirects to another article (cf. redirec_url) """
         raise NotImplementedError
 
-    def get_mime_type(self):
+    def get_mime_type(self) -> str:
+        """ MIME-type of the article's content. A/ namespace reserved to text/html """
         raise NotImplementedError
 
-    def get_filename(self):
+    def get_filename(self) -> str:
+        """ Filename to get content from. Blank string "" if not used """
         raise NotImplementedError
 
-    def should_compress(self):
+    def should_compress(self) -> bool:
+        """ Whether the article's content should be compressed or not """
         raise NotImplementedError
 
-    def should_index(self):
+    def should_index(self) -> bool:
+        """ Whether the article's content should be indexed or not """
         raise NotImplementedError
 
-    def redirect_url(self):
+    def redirect_url(self) -> str:
+        """ Full URL including namespace of another article """
         raise NotImplementedError
 
-    def _get_data(self):
+    def _get_data(self) -> Blob:
+        """ Internal data-retrieval with a cache to the content's pointer
+
+            You don't need to override this """
         if self._blob is None:
             self._blob = self.get_data()
         return self._blob
 
-    def get_data(self):
+    def get_data(self) -> Blob:
+        """ Blob containing the complete content of the article """
         raise NotImplementedError
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"{self.__class__.__name__}(url={self.get_url()}, title={self.get_title()})"
 
 
 class MetadataArticle(Article):
-    def __init__(self, url, metadata_content):
+    """ Simple Article sub-class for key-value articles on M/ metadata namespace """
+
+    def __init__(self, url: str, metadata_content: str):
         Article.__init__(self)
         self.url = url
         self.metadata_content = metadata_content
 
-    def is_redirect(self):
+    def is_redirect(self) -> bool:
         return False
 
-    def get_url(self):
+    def get_url(self) -> str:
         return f"M/{self.url}"
 
-    def get_title(self):
+    def get_title(self) -> str:
         return ""
 
-    def get_mime_type(self):
+    def get_mime_type(self) -> str:
         return "text/plain"
 
-    def get_filename(self):
+    def get_filename(self) -> str:
         return ""
 
-    def should_compress(self):
+    def should_compress(self) -> bool:
         return True
 
-    def should_index(self):
+    def should_index(self) -> bool:
         return False
 
-    def get_data(self):
+    def get_data(self) -> Blob:
         return Blob(self.metadata_content)
 
 
-def pascalize(keyword):
-    """ Converts python case to pascal case. example: long_description-> LongDescription """
-    return "".join(keyword.title().split("_"))
-
-
 class Creator:
-    """
-    A class to represent a Zim Creator.
-
-    Attributes
-    ----------
-    *c_creator : zim.Creator
-        a pointer to the C++ Creator object
-    _finalized : bool
-        flag if the creator was finalized
-    _filename : pathlib.Path
-        Zim file path
-    _main_page : str
-        Zim file main page
-    _index_language : str
-        Zim file Index language
-    _min_chunk_size : str
-        Zim file minimum chunk size
-    _article_counter
-        Zim file article counter
-    _metadata
-        Zim file metadata
-    """
-
-    def __init__(self, filename, main_page, index_language="eng", min_chunk_size=2048):
+    """ Zim Creator.
+
+        Attributes
+        ----------
+        *_creatorWrapper : wrapper.ZimCreatorWrapper
+            a pointer to the C++ Creator object wrapper
+        filename : pathlib.Path
+            Zim file path
+        main_page : str
+            Zim file main page (without namespace)
+        language : str
+            Zim file Index language
+        _article_counter
+            Zim file article counter
+        _metadata
+            Zim file metadata """
+
+    def __init__(
+        self, filename: pathlib.Path, main_page: str, index_language: str = "eng", min_chunk_size: int = 2048,
+    ):
+        """ Creates a ZIM Creator
+
+            Parameters
+            ----------
+            filename : Path to create the ZIM file at
+            main_page: ZIM file main article URL (without namespace, must be in A/)
+            index_language: content language to inform indexer with (ISO-639-3)
+            min_chunk_size: minimum size of chunks for compression """
+
         self._creatorWrapper = _Creator(str(filename), main_page, index_language, min_chunk_size)
         self.filename = pathlib.Path(filename)
         self.main_page = main_page
         self.language = index_language
         self._metadata = {}
-        self._article_counter = defaultdict(int)
+        self._article_counter = collections.defaultdict(int)
         self.update_metadata(date=datetime.date.today(), language=index_language)
+        self._closed = False
 
     def __enter__(self):
         return self
@@ -143,38 +175,59 @@ def __exit__(self, *args):
         self.close()
 
     def __del__(self):
-        self.close()
-
-    def add_article(self, article):
+        if not self._closed:
+            self.close()
+
+    def add_article(self, article: Article):
+        """ Adds an article to the Creator.
+
+            Parameters
+            ----------
+            article : Zim writer Article
+                The article to add to the file
+            Raises
+            ------
+                RuntimeError
+                    If the ZimCreator was already finalized """
         self._creatorWrapper.add_article(article)
         if not article.is_redirect():
-            self._update_article_counter(article)
-
-    def _update_article_counter(self, article):
-        # default dict update
-        self._article_counter[article.get_mime_type().strip()] += 1
+            # update article counter
+            self._article_counter[article.get_mime_type().strip()] += 1
 
     def update_metadata(self, **kwargs: str):
         """ Updates Creator metadata for ZIM, supplied as keyword arguments """
-        new_metadata = {pascalize(k): v for k, v in kwargs.items()}
-        self._metadata.update(new_metadata)
 
-    def write_metadata(self):
+        def pascalize(keyword: str):
+            """ Converts python case to pascal case.
+
+                example: long_description -> LongDescription """
+            return "".join(keyword.title().split("_"))
+
+        self._metadata.update({pascalize(k): v for k, v in kwargs.items()})
+
+    def close(self):
+        """ Finalizes and writes added articles to the file
+
+            Raises
+            ------
+                RuntimeError
+                    If the ZimCreator was already finalized """
+        if self._closed:
+            raise RuntimeError("Creator already closed")
+
+        # Store _medtadata dict as MetadataArticle
         for key, value in self._metadata.items():
-            if key == "Date" and isinstance(value, datetime.date):
+            if key == "Date" and isinstance(value, (datetime.date, datetime.datetime)):
                 value = value.strftime("%Y-%m-%d")
             article = MetadataArticle(key, value)
             self._creatorWrapper.add_article(article)
 
-        article = MetadataArticle("Counter", self._get_counter_string())
+        counter_str = ";".join([f"{k}={v}" for (k, v) in self._article_counter.items()])
+        article = MetadataArticle("Counter", counter_str)
         self._creatorWrapper.add_article(article)
 
-    def _get_counter_string(self):
-        return ";".join(["%s=%s" % (k, v) for (k, v) in self._article_counter.items()])
-
-    def close(self):
-        self.write_metadata()
         self._creatorWrapper.finalize()
+        self._closed = True
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"Creator(filename={self.filename})"