definition of abstract handler and implementation of handler for local filesystem

output_handlers/__init__.py

@@ -0,0 +1,2 @@
+from .base_handler import BaseHandler
+from .filesystm_handler import FileSystemHandler

output_handlers/base_handler.py

@@ -0,0 +1,54 @@
+"""Reference handler for output handlers."""
+from abc import ABC, abstractmethod
+import logging
+
+
+
+class BaseHandler(ABC):
+    """
+    Abstract base class for output handlers. Defines the standardized interface that all output handlers must implement.
+    In particular, it requires the implementation of an asynchronous ("private") method `_write_entry` to write a single entry to the output.
+    """
+
+    logger = logging.getLogger(__name__)
+
+    def __init__(self, fail_on_error: bool = True, **kwargs):
+        """
+        Initializes the BaseHandler with optional parameters.
+
+        Args:
+            fail_on_error (bool): If True, the handler will raise an exception on error. Defaults to True.
+            **kwargs: Additional keyword arguments for specific handler implementations.
+        """
+        self.fail_on_error = fail_on_error
+
+
+    @abstractmethod
+    async def _write_entry(self, entry: dict, uid: str) -> bool:
+        """
+        Asynchronously writes a single entry to the output. This method should gracefully handle any exceptions that may occur during the writing process and simply return False if an error occurs.
+
+        Args:
+            entry (dict): The entry to write (will be JSON-encoded).
+            uid (str): The unique identifier for the entry. The default id provided by wikivoyage is recommended. 
+        Returns:
+            bool: True if the entry was written successfully, False otherwise.
+        """
+        pass
+
+
+    async def write_entry(self, entry: dict, uid: str):
+        """
+        Public method to write an entry to the output. It handles exceptions and logs errors.
+
+        Args:
+            entry (dict): The entry to write (will be JSON-encoded).
+            uid (str): The unique identifier for the entry. The default id provided by wikivoyage is recommended. 
+        """
+        success = await self._write_entry(entry, uid)
+        if success:
+            self.logger.debug(f"Successfully wrote entry with UID {uid}")
+        else:
+            self.logger.error(f"Failed to write entry with UID {uid}")
+            if self.fail_on_error:
+                raise Exception(f"Failed to write entry with UID {uid}")

output_handlers/filesystm_handler.py

@@ -0,0 +1,43 @@
+"""Handler that writes files to the filesystem."""
+from pathlib import Path
+import aiofiles
+from .base_handler import BaseHandler
+
+class FileSystemHandler(BaseHandler):
+    """
+    Handler that writes files to the filesystem.
+    """
+    def __init__(self, output_dir: str, **kwargs):
+        """
+        Initializes the FileSystemHandler with the specified output directory.
+
+        Args:
+            output_dir (str): The directory where files will be written.
+            **kwargs: Additional keyword arguments for the BaseHandler.
+        """
+        super().__init__(**kwargs)
+        self.output_dir = Path(output_dir)
+        # Ensure the target directory exists
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+        self.logger.info(f"Output directory set to {self.output_dir}")
+
+
+    async def _write_entry(self, entry: dict, uid: str) -> bool:
+        """
+        Asynchronously writes a single entry to the filesystem.
+
+        Args:
+            entry (dict): The entry to write (will be JSON-encoded).
+            uid (str): The unique identifier for the entry.
+
+        Returns:
+            bool: True if the entry was written successfully, False otherwise.
+        """
+        try:
+            file_path = self.output_dir / f"{uid}.json"
+            async with aiofiles.open(file_path, 'w') as f:
+                await f.write(entry)
+            return True
+        except IOError as e:
+            self.logger.error(f"Error writing entry {uid}: {e}")
+            return False