From 429d6bf0e958fb02149ebada149fdfe5f57384f8 Mon Sep 17 00:00:00 2001
From: Brett Williams <blw1138@mac.com>
Date: Tue, 20 Aug 2024 23:01:16 -0500
Subject: [PATCH] Add docstrings to base_worker.py

---
 src/engines/core/base_worker.py | 79 ++++++++++++++++++++-------------
 1 file changed, 49 insertions(+), 30 deletions(-)

diff --git a/src/engines/core/base_worker.py b/src/engines/core/base_worker.py
index 9ab5c94..2ca2f72 100644
--- a/src/engines/core/base_worker.py
+++ b/src/engines/core/base_worker.py
@@ -48,6 +48,10 @@ class BaseRenderWorker(Base):
 
     engine = None
 
+    # --------------------------------------------
+    # Required Overrides for Subclasses:
+    # --------------------------------------------
+
     def __init__(self, input_path, output_path, engine_path, priority=2, args=None, ignore_extensions=True, parent=None,
                  name=None):
 
@@ -57,7 +61,7 @@ class BaseRenderWorker(Base):
                 logger.error(err_meg)
                 raise ValueError(err_meg)
         if not self.engine:
-            raise NotImplementedError("Engine not defined")
+            raise NotImplementedError(f"Engine not defined for {self.__class__.__name__}")
 
         def generate_id():
             import uuid
@@ -103,6 +107,50 @@ class BaseRenderWorker(Base):
         self.__last_output_time = None
         self.watchdog_timeout = 120
 
+    def generate_worker_subprocess(self):
+        """Generate a return a list of the command line arguments necessary to perform requested job
+        
+        Returns:
+            list[str]: list of command line arguments
+        """
+        raise NotImplementedError("generate_worker_subprocess not implemented")
+
+    def _parse_stdout(self, line):
+        """Parses a line of standard output from the renderer.
+
+        This method should be overridden in a subclass to implement the logic for processing
+        and interpreting a single line of output from the renderer's standard output stream.
+
+        On frame completion, the subclass should:
+            1. Update value of self.current_frame
+            2. Call self._send_frame_complete_notification()
+
+        Args:
+            line (str): A line of text from the renderer's standard output.
+
+        Raises:
+            NotImplementedError: If the method is not overridden in a subclass.
+        """
+        raise NotImplementedError(f"_parse_stdout not implemented for {self.__class__.__name__}")
+
+    # --------------------------------------------
+    # Optional Overrides for Subclasses:
+    # --------------------------------------------
+
+    def percent_complete(self):
+        # todo: fix this
+        if self.status == RenderStatus.COMPLETED:
+            return 1.0
+        return 0
+
+    def post_processing(self):
+        """Override to perform any engine-specific postprocessing"""
+        pass
+
+    # --------------------------------------------
+    # Do Not Override These Methods:
+    # --------------------------------------------
+
     def __repr__(self):
         return f"<Job id:{self.id} p{self.priority} {self.renderer}-{self.renderer_version} '{self.name}' status:{self.status.value}>"
 
@@ -149,9 +197,6 @@ class BaseRenderWorker(Base):
             raw_args = shlex.split(raw_args_string)
         return raw_args
 
-    def generate_worker_subprocess(self):
-        raise NotImplementedError("generate_worker_subprocess not implemented")
-
     def log_path(self):
         filename = (self.name or os.path.basename(self.input_path)) + '_' + \
                    self.date_created.strftime("%Y.%m.%d_%H.%M.%S") + '.log'
@@ -387,9 +432,6 @@ class BaseRenderWorker(Base):
         except Exception as e:
             logger.error(f"Error stopping the process: {e}")
 
-    def post_processing(self):
-        pass
-
     def is_running(self):
         if hasattr(self, '__thread'):
             return self.__thread.is_alive()
@@ -418,29 +460,6 @@ class BaseRenderWorker(Base):
         if self.is_running():  # allow the log files to close
             self.__thread.join(timeout=5)
 
-    def percent_complete(self):
-        if self.status == RenderStatus.COMPLETED:
-            return 1.0
-        return 0
-
-    def _parse_stdout(self, line):
-        """Parses a line of standard output from the renderer.
-
-        This method should be overridden in a subclass to implement the logic for processing
-        and interpreting a single line of output from the renderer's standard output stream.
-
-        On frame completion, the subclass should:
-            1. Update value of self.current_frame
-            2. Call self._send_frame_complete_notification()
-
-        Args:
-            line (str): A line of text from the renderer's standard output.
-
-        Raises:
-            NotImplementedError: If the method is not overridden in a subclass.
-        """
-        raise NotImplementedError(f"_parse_stdout not implemented for {self.__class__.__name__}")
-
     def time_elapsed(self):
         return get_time_elapsed(self.start_time, self.end_time)