Add missing docstrings and pylint improvements (#130)

src/api/job_import_handler.py

@@ -5,19 +5,77 @@ import shutil
 import tempfile
 import zipfile
 from datetime import datetime
+from pathlib import Path
 
 import requests
-from pathlib import Path
 from tqdm import tqdm
 from werkzeug.utils import secure_filename
 
+from distributed_job_manager import DistributedJobManager
+
 logger = logging.getLogger()
 
 
 class JobImportHandler:
+    """Handles job import operations for rendering projects.
+
+    This class provides functionality to validate, download, and process
+    job data and project files for the rendering queue system.
+    """
+
+    @classmethod
+    def create_jobs_from_processed_data(cls, processed_job_data: dict) -> list[dict]:
+        """ Takes processed job data and creates new jobs
+
+        Args: processed_job_data: Dictionary containing job information"""
+        loaded_project_local_path = processed_job_data['__loaded_project_local_path']
+
+        # prepare child job data
+        job_data_to_create = []
+        if processed_job_data.get("child_jobs"):
+            for child_job_diffs in processed_job_data["child_jobs"]:
+                processed_child_job_data = processed_job_data.copy()
+                processed_child_job_data.pop("child_jobs")
+                processed_child_job_data.update(child_job_diffs)
+                job_data_to_create.append(processed_child_job_data)
+        else:
+            job_data_to_create.append(processed_job_data)
+
+        # create the jobs
+        created_jobs = []
+        for job_data in job_data_to_create:
+            new_job = DistributedJobManager.create_render_job(job_data, loaded_project_local_path)
+            created_jobs.append(new_job)
+
+        # Save notes to .txt
+        if processed_job_data.get("notes"):
+            parent_dir = Path(loaded_project_local_path).parent.parent
+            notes_name = processed_job_data['name'] + "-notes.txt"
+            with (Path(parent_dir) / notes_name).open("w") as f:
+                f.write(processed_job_data["notes"])
+        return [x.json() for x in created_jobs]
 
     @classmethod
     def validate_job_data(cls, new_job_data: dict, upload_directory: Path, uploaded_file=None) -> dict:
+        """Validates and prepares job data for import.
+
+        This method validates the job data dictionary, handles project file
+        acquisition (upload, download, or local copy), and prepares the job
+        directory structure.
+
+        Args:
+            new_job_data: Dictionary containing job information including
+                'name', 'engine_name', and optionally 'url' or 'local_path'.
+            upload_directory: Base directory for storing uploaded jobs.
+            uploaded_file: Optional uploaded file object from the request.
+
+        Returns:
+            The validated job data dictionary with additional metadata.
+
+        Raises:
+            KeyError: If required fields 'name' or 'engine_name' are missing.
+            FileNotFoundError: If no valid project file can be found.
+        """
         loaded_project_local_path = None
 
         # check for required keys
@@ -25,7 +83,7 @@ class JobImportHandler:
         engine_name = new_job_data.get('engine_name')
         if not job_name:
             raise KeyError("Missing job name")
-        elif not engine_name:
+        if not engine_name:
             raise KeyError("Missing engine name")
 
         project_url = new_job_data.get('url', None)
@@ -45,8 +103,7 @@ class JobImportHandler:
 
         # Prepare the local filepath
         cleaned_path_name = job_name.replace(' ', '-')
-        timestamp = datetime.now().strftime("%Y.%m.%d_%H.%M.%S")
-        folder_name = f"{cleaned_path_name}-{engine_name}-{timestamp}"
+        folder_name = f"{cleaned_path_name}-{engine_name}-{datetime.now().strftime('%Y.%m.%d_%H.%M.%S')}"
         job_dir = Path(upload_directory) / folder_name
         os.makedirs(job_dir, exist_ok=True)
         project_source_dir = Path(job_dir) / 'source'
@@ -81,12 +138,24 @@ class JobImportHandler:
 
     @staticmethod
     def download_project_from_url(project_url: str):
+        """Downloads a project file from the given URL.
+
+        Downloads the file from the specified URL to a temporary directory
+        with progress tracking. Returns the filename and temporary path.
+
+        Args:
+            project_url: The URL to download the project file from.
+
+        Returns:
+            A tuple of (filename, temp_file_path) if successful,
+            (None, None) if download fails.
+        """
         # This nested function is to handle downloading from a URL
         logger.info(f"Downloading project from url: {project_url}")
         referred_name = os.path.basename(project_url)
 
         try:
-            response = requests.get(project_url, stream=True)
+            response = requests.get(project_url, stream=True, timeout=300)
             if response.status_code == 200:
                 # Get the total file size from the "Content-Length" header
                 file_size = int(response.headers.get("Content-Length", 0))
@@ -113,8 +182,8 @@ class JobImportHandler:
         """
         Processes a zipped project.
 
-        This method takes a path to a zip file, extracts its contents, and returns the path to the extracted project file.
-        If the zip file contains more than one project file or none, an error is raised.
+        This method takes a path to a zip file, extracts its contents, and returns the path to the extracted project
+        file. If the zip file contains more than one project file or none, an error is raised.
 
         Args:
             zip_path (Path): The path to the zip file.
@@ -148,5 +217,5 @@ class JobImportHandler:
 
         except (zipfile.BadZipFile, zipfile.LargeZipFile) as e:
             logger.error(f"Error processing zip file: {e}")
-            raise ValueError(f"Error processing zip file: {e}")
+            raise ValueError(f'Error processing zip file: {e}') from e
         return extracted_project_path