randex 0.3.1__tar.gz → 0.3.3__tar.gz

{randex-0.3.1 → randex-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: randex
-Version: 0.3.1
+Version: 0.3.3
 Summary: Create randomized multiple choice exams using latex.
 License: CC BY-NC 4.0
 Author: G. Arampatzis
@@ -70,57 +70,56 @@ probably have already `latexmk` installed as well.
 
 ## Randex Commands
 
-### randex-download-examples
+### randex download-examples
 
-To download the latest examples from GitHub, run the following command from the root
-folder of the project:
+To download the latest examples from GitHub, run the following command:
 
 ```sh
-randex-download-examples
+randex download-examples
 ```
 
-### validate
+### randex validate
 
 This command validates a single question or all questions under a folder. Execute:
 
 ```sh
-validate -t examples/en/template-exam.yaml -o tmp --overwrite "examples/en/folder_*"
+randex validate "examples/en/folder_*" -t examples/en/template-exam.yaml -o tmp --overwrite
 ```
 
 to validate all the questions under the folder `examples/en` that contains subfolders
 with questions.
 It will use the configuration from the file `examples/en/template-exam.yaml`.
-The LaTeX compilation will run inside the `temp` folder.
+The LaTeX compilation will run inside the `tmp` folder.
 The `--clean` option will remove all intermediate files created by LaTeX,
 and the `-a` flag will show the correct answers in the produced PDF.
-Open the PDF file inside `temp` to validate that all questions appear correctly.
+Open the PDF file inside `tmp` to validate that all questions appear correctly.
 
 Run:
 
 ```sh
-validate --help
+randex validate --help
 ```
 
 to see the help message for the command.
 
-### exams
+### randex batch
 
 To create a batch of exams with random questions, execute:
 
 ```sh
-exams -b 5 -n 2 -t examples/en/template-exam.yaml -o tmp --overwrite --clean "examples/en/folder_*"
+randex batch "examples/en/folder_*" 5 -n 2 -t examples/en/template-exam.yaml -o tmp --overwrite --clean
 ```
 
-This command will create 5 exams from using the questions inside  the 3 folders with
+This command will create 5 exams using the questions inside the 3 folders with
 names `folder_0`, `folder_1`, and `folder_2` using the configuration from the file
 `examples/en/template-exam.yaml`.
 The `--clean` option will remove all intermediate files created by LaTeX.
 The `-n` option specifies the number of questions randomly chosen from each folder.
 It can appear once, meaning all folders will contribute the same number of questions,
-or multiple times, e.g., `-n 2 -n 1 -n 3 `, indicating the first folder will contribute
+or multiple times, e.g., `-n 2 -n 1 -n 3`, indicating the first folder will contribute
 2 questions, the second folder will contribute 1 question, and the third folder will
 contribute 3 questions.
-The `-b` option specifies the number of exams to create.
+The batch size (5 in this example) specifies the number of exams to create.
 
 ### Grade
 

{randex-0.3.1 → randex-0.3.3}/README.md

@@ -44,57 +44,56 @@ probably have already `latexmk` installed as well.
 
 ## Randex Commands
 
-### randex-download-examples
+### randex download-examples
 
-To download the latest examples from GitHub, run the following command from the root
-folder of the project:
+To download the latest examples from GitHub, run the following command:
 
 ```sh
-randex-download-examples
+randex download-examples
 ```
 
-### validate
+### randex validate
 
 This command validates a single question or all questions under a folder. Execute:
 
 ```sh
-validate -t examples/en/template-exam.yaml -o tmp --overwrite "examples/en/folder_*"
+randex validate "examples/en/folder_*" -t examples/en/template-exam.yaml -o tmp --overwrite
 ```
 
 to validate all the questions under the folder `examples/en` that contains subfolders
 with questions.
 It will use the configuration from the file `examples/en/template-exam.yaml`.
-The LaTeX compilation will run inside the `temp` folder.
+The LaTeX compilation will run inside the `tmp` folder.
 The `--clean` option will remove all intermediate files created by LaTeX,
 and the `-a` flag will show the correct answers in the produced PDF.
-Open the PDF file inside `temp` to validate that all questions appear correctly.
+Open the PDF file inside `tmp` to validate that all questions appear correctly.
 
 Run:
 
 ```sh
-validate --help
+randex validate --help
 ```
 
 to see the help message for the command.
 
-### exams
+### randex batch
 
 To create a batch of exams with random questions, execute:
 
 ```sh
-exams -b 5 -n 2 -t examples/en/template-exam.yaml -o tmp --overwrite --clean "examples/en/folder_*"
+randex batch "examples/en/folder_*" 5 -n 2 -t examples/en/template-exam.yaml -o tmp --overwrite --clean
 ```
 
-This command will create 5 exams from using the questions inside  the 3 folders with
+This command will create 5 exams using the questions inside the 3 folders with
 names `folder_0`, `folder_1`, and `folder_2` using the configuration from the file
 `examples/en/template-exam.yaml`.
 The `--clean` option will remove all intermediate files created by LaTeX.
 The `-n` option specifies the number of questions randomly chosen from each folder.
 It can appear once, meaning all folders will contribute the same number of questions,
-or multiple times, e.g., `-n 2 -n 1 -n 3 `, indicating the first folder will contribute
+or multiple times, e.g., `-n 2 -n 1 -n 3`, indicating the first folder will contribute
 2 questions, the second folder will contribute 1 question, and the third folder will
 contribute 3 questions.
-The `-b` option specifies the number of exams to create.
+The batch size (5 in this example) specifies the number of exams to create.
 
 ### Grade
 

{randex-0.3.1 → randex-0.3.3}/pyproject.toml

@@ -53,7 +53,7 @@ packages = [
   {include = "scripts"}
 ]
 readme = "README.md"
-version = "0.3.1"
+version = "0.3.3"
 
 [tool.poetry.dependencies]
 cerberus = "^1.3.5"
@@ -141,6 +141,7 @@ ignore = [
   "FA100",
   "T201",
   "TRY003",
+  "TRY300",
   "ISC001",
   "N806",
   "N803",

{randex-0.3.1 → randex-0.3.3}/randex/exam.py

@@ -10,6 +10,7 @@ import logging
 import subprocess
 import time
 from collections import OrderedDict
+from concurrent.futures import ProcessPoolExecutor, as_completed
 from copy import deepcopy
 from dataclasses import dataclass, field
 from functools import cached_property
@@ -17,7 +18,7 @@ from pathlib import Path
 from random import sample, shuffle
 
 import yaml
-from pydantic import BaseModel, field_validator, model_validator
+from pydantic import BaseModel, ValidationError, field_validator, model_validator
 from pypdf import PdfWriter
 from typing_extensions import Self
 
@@ -792,6 +793,48 @@ class ExamBatch(BaseModel):
                     )
         return self
 
+    @staticmethod
+    def _compile_single_exam(
+        exam_data: dict,
+        exam_dir: Path,
+        clean: bool,
+    ) -> tuple[str, bool, str]:
+        """
+        Compile a single exam in a separate process.
+
+        Parameters
+        ----------
+        exam_data : dict
+            Serialized exam data
+        exam_dir : Path
+            Directory to compile the exam in
+        clean : bool
+            Whether to clean auxiliary files
+
+        Returns
+        -------
+        tuple[str, bool, str]
+            Tuple of (serial_number, success, error_message)
+        """
+        try:
+            exam_dir.mkdir(exist_ok=True, parents=True)
+
+            # Reconstruct the Exam object
+            from randex.exam import Exam
+
+            exam = Exam.model_validate(exam_data)
+            logger.info("Compiling exam %s", exam.sn)
+
+            result = exam.compile(exam_dir, clean)
+            pdf_path = exam_dir / "exam.pdf"
+
+            if result.returncode == 0 and pdf_path.exists():
+                return exam.sn, True, ""
+            return exam.sn, False, "LaTeX compilation failed or PDF not created"
+
+        except (ValidationError, subprocess.SubprocessError, OSError) as e:
+            return exam_data.get("sn", "unknown"), False, str(e)
+
     def make_batch(self) -> None:
         """Generate a batch of randomized exams."""
         serial_width = len(str(self.N))
@@ -816,23 +859,72 @@ class ExamBatch(BaseModel):
 
         logger.info("Successfully created %s exams", len(self.exams))
 
-    def compile(self, path: Path | str, clean: bool = False) -> None:
+    def _run_parallel_compilation(
+        self, path: Path, clean: bool
+    ) -> tuple[list[Path], list[str]]:
         """
-        Compile all exams and merge into a single PDF.
+        Run parallel compilation of all exams.
 
-        Parameters
-        ----------
-        path : Path | str
-            The path to the directory where the exams will be compiled.
-        clean : bool
-            Whether to clean the LaTeX auxiliary files.
+        Returns
+        -------
+        tuple[list[Path], list[str]]
+            Tuple of (pdf_files, failed_exams)
         """
-        if not self.exams:
-            raise RuntimeError("No exams to compile. Call make_batch() first.")
+        # Prepare compilation tasks
+        compilation_tasks = []
+        for exam in self.exams:
+            exam_dir = path / exam.sn
+            exam_data = exam.model_dump(mode="json")
+            compilation_tasks.append((exam_data, exam_dir, clean))
 
-        path = Path(path).resolve()
-        path.mkdir(exist_ok=True, parents=True)
+        logger.info("🚀 Starting parallel compilation of %d exams...", len(self.exams))
+
+        pdf_files = []
+        failed = []
+
+        with ProcessPoolExecutor() as executor:
+            future_to_sn = {
+                executor.submit(
+                    ExamBatch._compile_single_exam,
+                    exam_data,
+                    exam_dir,
+                    clean,
+                ): exam_data["sn"]
+                for exam_data, exam_dir, clean in compilation_tasks
+            }
+
+            for future in as_completed(future_to_sn):
+                sn = future_to_sn[future]
+                try:
+                    serial_number, success, error_msg = future.result()
+                    if success:
+                        pdf_path = path / serial_number / "exam.pdf"
+                        pdf_files.append(pdf_path)
+                        logger.debug("✅ Successfully compiled exam %s", serial_number)
+                    else:
+                        logger.error(
+                            "❌ Failed to compile exam %s: %s",
+                            serial_number,
+                            error_msg,
+                        )
+                        failed.append(serial_number)
+                except Exception:
+                    logger.exception("💥 Error compiling exam %s", sn)
+                    failed.append(sn)
 
+        return pdf_files, failed
+
+    def _run_sequential_compilation(
+        self, path: Path, clean: bool
+    ) -> tuple[list[Path], list[str]]:
+        """
+        Run sequential compilation of all exams (for backward compatibility).
+
+        Returns
+        -------
+        tuple[list[Path], list[str]]
+            Tuple of (pdf_files, failed_exams)
+        """
         pdf_files = []
         failed = []
 
@@ -847,19 +939,51 @@ class ExamBatch(BaseModel):
                 pdf_path = exam_dir / "exam.pdf"
                 if result.returncode == 0 and pdf_path.exists():
                     pdf_files.append(pdf_path)
+                    logger.debug("✅ Successfully compiled exam %s", exam.sn)
                 else:
-                    logger.error("PDF not created or failed for exam %s", exam.sn)
+                    logger.error("❌ PDF not created or failed for exam %s", exam.sn)
                     failed.append(exam.sn)
 
             except Exception:
-                logger.exception("Error compiling exam %s", exam.sn)
+                logger.exception("💥 Error compiling exam %s", exam.sn)
                 failed.append(exam.sn)
 
+        return pdf_files, failed
+
+    def compile(
+        self, path: Path | str, clean: bool = False, parallel: bool = True
+    ) -> None:
+        """
+        Compile all exams and merge into a single PDF.
+
+        Parameters
+        ----------
+        path : Path | str
+            The path to the directory where the exams will be compiled.
+        clean : bool
+            Whether to clean the LaTeX auxiliary files.
+        parallel : bool
+            Whether to use parallel compilation. Defaults to True.
+        """
+        if not self.exams:
+            raise RuntimeError("No exams to compile. Call make_batch() first.")
+
+        path = Path(path).resolve()
+        path.mkdir(exist_ok=True, parents=True)
+
+        if parallel:
+            pdf_files, failed = self._run_parallel_compilation(path, clean)
+        else:
+            pdf_files, failed = self._run_sequential_compilation(path, clean)
+
         if failed:
             logger.warning("Failed to compile exams: %s", ", ".join(failed))
         if not pdf_files:
             raise RuntimeError("No exams compiled successfully")
 
+        # Sort PDF files by serial number to ensure consistent ordering
+        pdf_files.sort(key=lambda pdf_path: pdf_path.parent.name)
+
         merged_path = path / "exams.pdf"
         merger = PdfWriter()
 
@@ -873,9 +997,11 @@ class ExamBatch(BaseModel):
             with open(merged_path, "wb") as f:
                 merger.write(f)
 
+            compilation_type = "parallel" if parallel else "sequential"
             logger.info(
-                "Successfully merged %s PDFs into %s",
+                "🎉 Successfully compiled %s exams %s and merged into %s",
                 len(pdf_files),
+                compilation_type,
                 merged_path,
             )
 

{randex-0.3.1 → randex-0.3.3}/scripts/batch.py

@@ -23,6 +23,7 @@ def main(
     out_folder: Path | None,
     clean: bool,
     overwrite: bool,
+    sequential: bool,
 ) -> None:
     """
     Create a batch of exams with randomly chosen multiple choice questions.
@@ -43,6 +44,8 @@ def main(
         Clean the output folder before creating the exams.
     overwrite : bool
         Overwrite the output folder if it already exists.
+    sequential : bool
+        Use sequential compilation instead of parallel.
     """
     if out_folder is None:
         out_folder = Path(f"tmp_{datetime.now().strftime('%Y-%m-%d_%H-%M-%S')}")
@@ -87,13 +90,9 @@ def main(
     b.make_batch()
 
     logger.info("🔨 Compiling exams...")
-    b.compile(clean=clean, path=out_folder)
+    b.compile(clean=clean, path=out_folder, parallel=not sequential)
 
     logger.info("💾 Saving batch configuration to: %s", out_folder / "exams.yaml")
     b.save(out_folder / "exams.yaml")
 
-    logger.debug("🔄 Reloading and recompiling batch...")
-    b = ExamBatch.load(out_folder / "exams.yaml")
-    b.compile(clean=clean, path=out_folder)
-
     logger.info("✅ Batch creation completed successfully in: %s", out_folder)

{randex-0.3.1 → randex-0.3.3}/scripts/randex.py

@@ -115,6 +115,12 @@ def download_examples() -> None:
     default=False,
     help="Overwrite the out-folder if it already exists (use with caution).",
 )
+@click.option(
+    "--sequential",
+    is_flag=True,
+    default=False,
+    help="Use sequential compilation instead of parallel.",
+)
 def batch(
     folder: str,
     batch_size: int,
@@ -123,6 +129,7 @@ def batch(
     out_folder: Path | None,
     clean: bool,
     overwrite: bool,
+    sequential: bool,
 ) -> None:
     """
     Create a batch of exams with randomly chosen multiple choice questions.
@@ -148,6 +155,7 @@ def batch(
         out_folder=out_folder,
         clean=clean,
         overwrite=overwrite,
+        sequential=sequential,
     )