randex 0.2.1__tar.gz → 0.3.2__tar.gz

{randex-0.2.1 → randex-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: randex
-Version: 0.2.1
+Version: 0.3.2
 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.2.1 → randex-0.3.2}/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.2.1 → randex-0.3.2}/pyproject.toml

@@ -53,7 +53,7 @@ packages = [
   {include = "scripts"}
 ]
 readme = "README.md"
-version = "0.2.1"
+version = "0.3.2"
 
 [tool.poetry.dependencies]
 cerberus = "^1.3.5"
@@ -76,9 +76,7 @@ pytest-cov = "^6.2.1"
 types-pyyaml = "^6.0.12.20250516"
 
 [tool.poetry.scripts]
-exams = "scripts.exams:main"
-randex-download-examples = "scripts.randex_download_examples:main"
-validate = "scripts.validate:main"
+randex = "scripts.randex:cli"
 
 [tool.poetry.urls]
 "Homepage" = "https://github.com/arampatzis/randex"

{randex-0.2.1 → randex-0.3.2}/randex/cli.py

@@ -1,8 +1,82 @@
 """Shared CLI utilities for randex scripts."""
 
+import logging
+import sys
+
 import click
 
 
+def setup_logging(verbose: int = 0, quiet: bool = False) -> None:
+    """
+    Set up logging configuration for the CLI.
+
+    Parameters
+    ----------
+    verbose : int
+        Verbosity level (0=INFO, 1=DEBUG, 2+ more verbose DEBUG)
+    quiet : bool
+        If True, only show warnings and errors
+    """
+    if quiet:
+        level = logging.WARNING
+    elif verbose >= 1:
+        level = logging.DEBUG
+    else:
+        level = logging.INFO
+
+    # Create formatter
+    formatter = logging.Formatter(fmt="%(message)s", datefmt="%Y-%m-%d %H:%M:%S")
+
+    # Set up the root logger
+    logger = logging.getLogger()
+    logger.setLevel(level)
+
+    # Remove any existing handlers
+    for handler in logger.handlers[:]:
+        logger.removeHandler(handler)
+
+    # Create console handler
+    handler = logging.StreamHandler(sys.stdout)
+    handler.setLevel(level)
+    handler.setFormatter(formatter)
+
+    logger.addHandler(handler)
+
+    # For verbose mode, also show logger names and levels
+    if verbose >= 2:
+        formatter = logging.Formatter(
+            fmt="[%(levelname)s] %(name)s: %(message)s", datefmt="%Y-%m-%d %H:%M:%S"
+        )
+        handler.setFormatter(formatter)
+
+
+def get_logger(name: str | None = None) -> logging.Logger:
+    """
+    Get a logger instance.
+
+    Parameters
+    ----------
+    name : str, optional
+        Logger name. If None, uses the calling module name.
+
+    Returns
+    -------
+    logging.Logger
+        Configured logger instance
+    """
+    if name is None:
+        # Get the calling module name
+        import inspect
+
+        frame = inspect.currentframe()
+        if frame and frame.f_back:
+            name = frame.f_back.f_globals.get("__name__", "randex")
+        else:
+            name = "randex"
+
+    return logging.getLogger(name)
+
+
 class CustomCommand(click.Command):
     """Custom Click command that provides better error messages."""
 

{randex-0.2.1 → randex-0.3.2}/randex/exam.py

@@ -299,6 +299,10 @@ class Pool:
 
     def print_questions(self) -> None:
         """Print all questions in the pool grouped by folder."""
+        from randex.cli import get_logger
+
+        logger = get_logger(__name__)
+
         first = True
         for folder, question_list in sorted(
             self.questions.items(),
@@ -308,18 +312,19 @@ class Pool:
                 continue
 
             if not first:
-                print("\n" + "-" * 60)
+                s = "\n" + "-" * 60
+                logger.info(s)
             first = False
 
-            print(f"\n\U0001f4c1 {folder}\n")
+            logger.info("\n\U0001f4c1 %s\n", folder)
             for i, question in enumerate(question_list):
-                print(f"  \U0001f4c4 Question {i + 1}")
-                print(f"    Q: {question.question}")
-                print("    Answers:")
+                logger.info("  \U0001f4c4 Question %d", i + 1)
+                logger.info("    Q: %s", question.question)
+                logger.info("    Answers:")
                 for j, ans in enumerate(question.answers):
                     mark = "✅" if j == question.right_answer else "  "
-                    print(f"      {mark} {j}. {ans}")
-                print("\n")
+                    logger.info("      %s %d. %s", mark, j, ans)
+                logger.info("\n")
 
 
 class QuestionSet(BaseModel):

randex-0.3.2/scripts/batch.py

@@ -0,0 +1,99 @@
+"""Script that creates a batch of randomized exams."""
+
+import shutil
+import sys
+from datetime import datetime
+from pathlib import Path
+
+import click
+from pydantic import ValidationError
+
+from randex.cli import get_logger
+from randex.exam import ExamBatch, ExamTemplate, Pool, QuestionSet
+
+logger = get_logger(__name__)
+
+
+def main(
+    *,
+    folder: str,
+    number_of_questions: list | int,
+    batch_size: int,
+    template_tex_path: Path,
+    out_folder: Path | None,
+    clean: bool,
+    overwrite: bool,
+) -> None:
+    """
+    Create a batch of exams with randomly chosen multiple choice questions.
+
+    Parameters
+    ----------
+    folder : str
+        Path or quoted glob (e.g. "examples/en/folder_*").
+    number_of_questions : list | int
+        Number of questions to sample.
+    batch_size : int
+        Number of exams to be created.
+    template_tex_path : Path
+        Path to the YAML file that contains the template for the exam configuration.
+    out_folder : Path | None
+        Create the batch exams in this folder (default: tmp_HH-MM-SS).
+    clean : bool
+        Clean the output folder before creating the exams.
+    overwrite : bool
+        Overwrite the output folder if it already exists.
+    """
+    if out_folder is None:
+        out_folder = Path(f"tmp_{datetime.now().strftime('%Y-%m-%d_%H-%M-%S')}")
+
+    logger.info("📁 Output folder: %s", out_folder)
+
+    if out_folder.exists():
+        if not overwrite:
+            raise click.UsageError(
+                f"Output folder '{out_folder}' already exists.\n"
+                "Use --overwrite to remove it and continue.",
+            )
+        logger.warning("🗑️  Removing existing output folder: %s", out_folder)
+        shutil.rmtree(out_folder)
+
+    if isinstance(number_of_questions, list | tuple) and len(number_of_questions) == 1:
+        number_of_questions = number_of_questions[0]
+
+    logger.info("📂 Loading questions from: %s", folder)
+    pool = Pool(folder=folder)
+
+    pool.print_questions()
+    questions_set = QuestionSet(questions=pool.questions)  # type: ignore[arg-type]
+    questions_set.sample(n=number_of_questions)
+
+    logger.info("📄 Loading exam template from: %s", template_tex_path)
+    exam_template = ExamTemplate.load(template_tex_path)
+
+    try:
+        logger.info("🔄 Creating batch of %d exams...", batch_size)
+        b = ExamBatch(
+            N=batch_size,
+            questions_set=questions_set,
+            exam_template=exam_template,
+            n=number_of_questions,
+        )
+    except ValidationError as e:
+        logger.exception("❌ Validation error while creating exam batch:")
+        logger.exception(e.json(indent=2))
+        sys.exit(1)
+
+    b.make_batch()
+
+    logger.info("🔨 Compiling exams...")
+    b.compile(clean=clean, path=out_folder)
+
+    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.2.1/scripts/randex_download_examples.py → randex-0.3.2/scripts/download_examples.py

@@ -9,49 +9,54 @@ import zipfile
 from pathlib import Path
 from urllib.error import URLError
 
+from randex.cli import get_logger
+
+logger = get_logger(__name__)
+
 GITHUB_ZIP_URL = "https://github.com/arampatzis/randex/archive/refs/heads/main.zip"
 DEST_DIR = Path("examples")
 
 
 def main() -> None:
     """Download the latest examples from GitHub."""
-    print("📦 Downloading examples from GitHub...")
+    logger.info("📦 Downloading examples from GitHub...")
 
     if DEST_DIR.exists():
-        print(
-            f"❌ Destination folder '{DEST_DIR}' already exists. "
-            "Please remove it first."
+        logger.error(
+            "❌ Destination folder '%s' already exists. Please remove it first."
         )
         sys.exit(1)
 
     try:
+        logger.debug("🌐 Fetching from: %s", GITHUB_ZIP_URL)
         with (
             urllib.request.urlopen(GITHUB_ZIP_URL) as response,  # noqa: S310
             zipfile.ZipFile(io.BytesIO(response.read())) as zip_ref,
         ):
             temp_dir = Path(tempfile.mkdtemp())
+            logger.debug("📁 Extracting to temporary directory: %s", temp_dir)
             zip_ref.extractall(temp_dir)
 
             # Detect the root folder inside the zip (e.g., randex-main)
             root_entry = next((p for p in temp_dir.iterdir() if p.is_dir()), None)
 
             if not root_entry:
-                print("❌ Could not locate the root folder in the archive.")
+                logger.error("❌ Could not locate the root folder in the archive.")
                 sys.exit(1)
 
             examples_path = root_entry / "examples"
+            logger.debug("🔍 Looking for examples in: %s", examples_path)
 
             if not examples_path.exists():
-                print("❌ examples/ folder not found in the downloaded repository.")
+                logger.error(
+                    "❌ examples/ folder not found in the downloaded repository."
+                )
                 sys.exit(1)
 
+            logger.debug("📂 Copying examples from %s to %s", examples_path, DEST_DIR)
             shutil.copytree(examples_path, DEST_DIR)
-            print(f"✅ Examples downloaded to: {DEST_DIR.resolve()}")
+            logger.info("✅ Examples downloaded to: %s", DEST_DIR.resolve())
 
-    except (URLError, zipfile.BadZipFile, OSError, shutil.Error) as e:
-        print(f"❌ Error: {e}")
+    except (URLError, zipfile.BadZipFile, OSError, shutil.Error):
+        logger.exception("❌ Error occurred during the download process.")
         sys.exit(1)
-
-
-if __name__ == "__main__":
-    main()

randex-0.3.2/scripts/randex.py

@@ -0,0 +1,228 @@
+"""Main CLI for randex - Create randomized multiple choice exams using latex."""
+
+import importlib.metadata
+from pathlib import Path
+
+import click
+
+from randex.cli import CustomCommand, setup_logging
+from scripts.batch import main as batch_main
+from scripts.download_examples import main as download_examples_main
+from scripts.validate import main as validate_main
+
+try:
+    __version__ = importlib.metadata.version("randex")
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0"
+
+
+# Main CLI group
+@click.group()
+@click.version_option(version=__version__, prog_name="randex")
+@click.option(
+    "--verbose",
+    "-v",
+    count=True,
+    help="Increase verbosity (use -v for DEBUG, -vv for more detailed DEBUG output)",
+)
+@click.option(
+    "--quiet", "-q", is_flag=True, help="Quiet mode - only show warnings and errors"
+)
+@click.pass_context
+def cli(ctx: click.Context, verbose: int, quiet: bool) -> None:
+    """randex: A CLI tool to create randomized multiple choice exams using latex."""
+    # Set up logging before any command runs
+    setup_logging(verbose=verbose, quiet=quiet)
+
+    # Store logging config in context for subcommands
+    ctx.ensure_object(dict)
+    ctx.obj["verbose"] = verbose
+    ctx.obj["quiet"] = quiet
+
+
+# Subcommand: download-examples # noqa: ERA001
+@cli.command(
+    cls=CustomCommand,
+    context_settings={"help_option_names": ["--help"]},
+)
+def download_examples() -> None:
+    """Download the latest examples from GitHub."""
+    download_examples_main()
+
+
+@cli.command(
+    cls=CustomCommand,
+    context_settings={"help_option_names": ["--help"]},
+)
+@click.argument(
+    "folder",
+    type=str,
+    nargs=1,
+    required=True,
+)
+@click.option(
+    "--batch-size",
+    "-b",
+    type=int,
+    default=1,
+    help="Number of exams to be created",
+)
+@click.option(
+    "--number_of_questions",
+    "-n",
+    type=int,
+    default=[1],
+    multiple=True,
+    help="""
+    Specify how many questions to sample.
+
+    - Use once: sample total number of questions from all folders.
+    Example: -n 10
+
+    - Use multiple times: sample per-folder counts, in order.
+    Example: -n 5 -n 3   # 5 from folder 1, 3 from folder 2
+    """,
+)
+@click.option(
+    "--template-tex-path",
+    "-t",
+    type=click.Path(
+        exists=True,
+        resolve_path=True,
+        file_okay=True,
+        dir_okay=False,
+        path_type=Path,
+    ),
+    required=True,
+    help="Path to the YAML file that contains the template for the exam configuration",
+)
+@click.option(
+    "--out-folder",
+    "-o",
+    type=Path,
+    help="Create the batch exams in this folder (default: tmp_HH-MM-SS)",
+)
+@click.option(
+    "--clean",
+    "-c",
+    is_flag=True,
+    default=False,
+    help="Clean all latex compilation auxiliary files",
+)
+@click.option(
+    "--overwrite",
+    is_flag=True,
+    default=False,
+    help="Overwrite the out-folder if it already exists (use with caution).",
+)
+def batch(
+    folder: str,
+    batch_size: int,
+    number_of_questions: list | int,
+    template_tex_path: Path,
+    out_folder: Path | None,
+    clean: bool,
+    overwrite: bool,
+) -> None:
+    """
+    Create a batch of exams with randomly chosen multiple choice questions.
+
+    The questions are loaded from a list of FOLDERS.
+
+    FOLDER: Path or quoted glob (e.g. "data/unit_*").
+
+    The questions are loaded from the FOLDERs and must follow the format:
+
+    question: What is $1+1$?
+    answers: ["0", "1", "2", "3"]
+    right_answer: 2
+
+    💡 Remember to wrap glob patterns in quotes to prevent shell expansion!
+
+    """
+    batch_main(
+        folder=folder,
+        batch_size=batch_size,
+        number_of_questions=number_of_questions,
+        template_tex_path=template_tex_path,
+        out_folder=out_folder,
+        clean=clean,
+        overwrite=overwrite,
+    )
+
+
+@cli.command(
+    cls=CustomCommand,
+    context_settings={"help_option_names": ["--help"]},
+)
+@click.argument(
+    "folder",
+    type=str,
+    nargs=1,
+    required=True,
+)
+@click.option(
+    "--template-tex-path",
+    "-t",
+    type=click.Path(
+        exists=True,
+        resolve_path=True,
+        file_okay=True,
+        dir_okay=False,
+        path_type=Path,
+    ),
+    required=True,
+    help="Path to the YAML file that contains the template for the exam configuration",
+)
+@click.option(
+    "--out-folder",
+    "-o",
+    type=Path,
+    default=".",
+    help="Run the latex compiler inside this folder",
+)
+@click.option(
+    "--clean",
+    "-c",
+    is_flag=True,
+    default=False,
+    help="Clean all latex compilation auxiliary files.",
+)
+@click.option(
+    "--show-answers",
+    "-a",
+    is_flag=True,
+    default=False,
+    help="Show the right answers on the pdf",
+)
+@click.option(
+    "--overwrite",
+    is_flag=True,
+    default=False,
+    help="Overwrite the out-folder if it already exists (use with caution).",
+)
+def validate(
+    folder: str,
+    template_tex_path: Path,
+    out_folder: Path,
+    clean: bool,
+    show_answers: bool,
+    overwrite: bool,
+) -> None:
+    """
+    Create a pdf file with all the questions defined in FOLDER.
+
+    The FOLDER is traversed recursively to load all questions.
+    """
+    validate_main(
+        folder=folder,
+        template_tex_path=template_tex_path,
+        out_folder=out_folder,
+        clean=clean,
+        show_answers=show_answers,
+        overwrite=overwrite,
+    )
+
+
+if __name__ == "__main__":
+    cli()

randex-0.3.2/scripts/validate.py

@@ -0,0 +1,129 @@
+"""Script that validates a single question, or all questions inside a folder."""
+
+import logging
+import shutil
+import subprocess
+from datetime import datetime
+from pathlib import Path
+
+import click
+
+from randex.cli import get_logger
+from randex.exam import Exam, ExamTemplate, Pool, QuestionSet
+
+logger = get_logger(__name__)
+
+
+def _setup_output_folder(out_folder: Path | str | None, overwrite: bool) -> Path:
+    """
+    Set up the output folder for validation.
+
+    Parameters
+    ----------
+    out_folder : Path | None
+        The output folder path, or None to generate a default.
+    overwrite : bool
+        Whether to overwrite existing folders.
+
+    Returns
+    -------
+    Path
+        The prepared output folder path.
+    """
+    if out_folder is None:
+        out_folder = Path(f"tmp_{datetime.now().strftime('%Y-%m-%d_%H-%M-%S')}")
+
+    out_folder = Path(out_folder)
+
+    logger.info("📁 Output folder: %s", out_folder)
+
+    if out_folder.exists():
+        if not overwrite:
+            raise click.UsageError(
+                f"Output folder '{out_folder}' already exists.\n"
+                "Use --overwrite to remove it and continue.",
+            )
+        logger.warning("🗑️  Removing existing output folder: %s", out_folder)
+        shutil.rmtree(out_folder)
+
+    return out_folder
+
+
+def _handle_compilation_result(
+    result: subprocess.CompletedProcess,
+    out_folder: Path | str,
+) -> None:
+    """
+    Handle and log the compilation results.
+
+    Parameters
+    ----------
+    result : subprocess.CompletedProcess
+        The compilation result from LaTeX.
+    out_folder : Path
+        The output folder path for success messages.
+    """
+    if result.stdout:
+        logger.debug("LaTeX compilation STDOUT:")
+        for line in result.stdout.splitlines():
+            logger.debug("  %s", line)
+
+    if result.stderr:
+        if result.returncode != 0:
+            logger.error("LaTeX compilation STDERR:")
+            for line in result.stderr.splitlines():
+                logger.error("  %s", line)
+        else:
+            logger.debug("LaTeX compilation STDERR:")
+            for line in result.stderr.splitlines():
+                logger.debug("  %s", line)
+
+    if result.returncode == 0:
+        logger.info("✅ Validation completed successfully in: %s", out_folder)
+    else:
+        logger.error(
+            "❌ LaTeX compilation failed with return code: %d", result.returncode
+        )
+
+
+def main(
+    *,
+    folder: Path | str,
+    template_tex_path: Path | str,
+    out_folder: Path | str | None,
+    clean: bool,
+    show_answers: bool,
+    overwrite: bool,
+) -> None:
+    """
+    Create a pdf file with all the questions defined in FOLDER.
+
+    The FOLDER is traversed recursively.
+    """
+    out_folder = _setup_output_folder(out_folder, overwrite)
+
+    logger.info("📂 Loading questions from: %s", folder)
+    pool = Pool(folder=folder)
+
+    if logger.isEnabledFor(logging.DEBUG):
+        pool.print_questions()
+
+    questions_set = QuestionSet(questions=pool.questions)  # type: ignore[arg-type]
+    number_of_questions = questions_set.size()
+    questions = questions_set.sample(n=number_of_questions)
+
+    logger.info("📄 Loading exam template from: %s", template_tex_path)
+    exam_template = ExamTemplate.load(Path(template_tex_path))
+
+    logger.info("📝 Creating validation exam with %d questions", number_of_questions)
+    exam = Exam(
+        exam_template=exam_template,
+        questions=questions,
+        show_answers=show_answers,
+    )
+    exam.apply_shuffling(shuffle_questions=True, shuffle_answers=True)
+
+    logger.info("🔨 Compiling exam...")
+    result = exam.compile(path=out_folder, clean=clean)
+
+    _handle_compilation_result(result, out_folder)

randex-0.2.1/scripts/exams.py

@@ -1,138 +0,0 @@
-"""Script that creates a batch of randomized exams."""
-
-import shutil
-from datetime import datetime
-from pathlib import Path
-
-import click
-
-from randex.cli import CustomCommand
-from randex.exam import ExamBatch, ExamTemplate, Pool, QuestionSet
-
-
-@click.command(
-    cls=CustomCommand,
-    context_settings={"help_option_names": ["--help"]},
-)
-@click.argument(
-    "folder",
-    type=str,
-    nargs=1,
-    required=True,
-)
-@click.option(
-    "--batch-size",
-    "-b",
-    type=int,
-    default=1,
-    help="Number of exams to be created",
-)
-@click.option(
-    "--number_of_questions",
-    "-n",
-    type=int,
-    default=[1],
-    multiple=True,
-    help="""
-    Specify how many questions to sample.
-
-    - Use once: sample total number of questions from all folders.
-    Example: -n 10
-
-    - Use multiple times: sample per-folder counts, in order.
-    Example: -n 5 -n 3   # 5 from folder 1, 3 from folder 2
-    """,
-)
-@click.option(
-    "--template-tex-path",
-    "-t",
-    type=click.Path(
-        exists=True,
-        resolve_path=True,
-        file_okay=True,
-        dir_okay=False,
-        path_type=Path,
-    ),
-    required=True,
-    help="Path to the YAML file that contains the template for the exam configuration",
-)
-@click.option(
-    "--out-folder",
-    "-o",
-    type=Path,
-    help="Create the batch exams in this folder (default: tmp_HH-MM-SS)",
-)
-@click.option(
-    "--clean",
-    "-c",
-    is_flag=True,
-    default=False,
-    help="Clean all latex compilation auxiliary files",
-)
-@click.option(
-    "--overwrite",
-    is_flag=True,
-    default=False,
-    help="Overwrite the out-folder if it already exists (use with caution).",
-)
-def main(
-    folder: str,
-    number_of_questions: list | int,
-    batch_size: int,
-    template_tex_path: Path,
-    out_folder: Path | None,
-    clean: bool,
-    overwrite: bool,
-) -> None:
-    """
-    Create a batch of exams with randomly chosen multiple choice questions.
-
-    The questions are loaded from a list of FOLDERS.
-
-    FOLDER: Path or quoted glob (e.g. "data/unit_*").
-
-    The questions are loaded from the FOLDERs and must follow the format:
-
-    question: What is $1+1$?
-    answers: ["0", "1", "2", "3"]
-    right_answer: 2
-
-    💡 Remember to wrap glob patterns in quotes to prevent shell expansion!
-    """
-    if out_folder is None:
-        out_folder = Path(f"tmp_{datetime.now().strftime('%Y-%m-%d_%H-%M-%S')}")
-
-    if out_folder.exists():
-        if not overwrite:
-            raise click.UsageError(
-                f"Output folder '{out_folder}' already exists.\n"
-                "Use --overwrite to remove it and continue.",
-            )
-        shutil.rmtree(out_folder)
-
-    if isinstance(number_of_questions, list | tuple) and len(number_of_questions) == 1:
-        number_of_questions = number_of_questions[0]
-
-    pool = Pool(folder=folder)
-
-    pool.print_questions()
-    questions_set = QuestionSet(questions=pool.questions)  # type: ignore[arg-type]
-    questions_set.sample(n=number_of_questions)
-    exam_template = ExamTemplate.load(template_tex_path)
-
-    b = ExamBatch(
-        N=batch_size,
-        questions_set=questions_set,
-        exam_template=exam_template,
-        n=number_of_questions,
-    )
-
-    b.make_batch()
-
-    b.compile(clean=clean, path=out_folder)
-
-    b.save(out_folder / "exams.yaml")
-
-    b = ExamBatch.load(out_folder / "exams.yaml")
-
-    b.compile(clean=clean, path=out_folder)

randex-0.2.1/scripts/validate.py

@@ -1,107 +0,0 @@
-"""Script that validates a single question, or all questions inside a folder."""
-
-import shutil
-from datetime import datetime
-from pathlib import Path
-
-import click
-
-from randex.cli import CustomCommand
-from randex.exam import Exam, ExamTemplate, Pool, QuestionSet
-
-
-@click.command(
-    cls=CustomCommand,
-    context_settings={"help_option_names": ["--help"]},
-)
-@click.argument(
-    "folder",
-    type=str,
-    nargs=1,
-    required=True,
-)
-@click.option(
-    "--template-tex-path",
-    "-t",
-    type=click.Path(
-        exists=True,
-        resolve_path=True,
-        file_okay=True,
-        dir_okay=False,
-        path_type=Path,
-    ),
-    required=True,
-    help="Path to the YAML file that contains the template for the exam configuration",
-)
-@click.option(
-    "--out-folder",
-    "-o",
-    type=Path,
-    default=".",
-    help="Run the latex compiler inside this folder",
-)
-@click.option(
-    "--clean",
-    "-c",
-    is_flag=True,
-    default=False,
-    help="Clean all latex compilation auxiliary files.",
-)
-@click.option(
-    "--show-answers",
-    "-a",
-    is_flag=True,
-    default=False,
-    help="Show the right answers on the pdf",
-)
-@click.option(
-    "--overwrite",
-    is_flag=True,
-    default=False,
-    help="Overwrite the out-folder if it already exists (use with caution).",
-)
-def main(
-    folder: Path,
-    template_tex_path: Path,
-    out_folder: Path,
-    clean: bool,
-    show_answers: bool,
-    overwrite: bool,
-) -> None:
-    """
-    Create a pdf file with all the questions defined in FOLDER.
-
-    The FOLDER is traversed recursively.
-    """
-    if out_folder is None:
-        out_folder = Path(f"tmp_{datetime.now().strftime('%Y-%m-%d_%H-%M-%S')}")
-
-    if out_folder.exists():
-        if not overwrite:
-            raise click.UsageError(
-                f"Output folder '{out_folder}' already exists.\n"
-                "Use --overwrite to remove it and continue.",
-            )
-        shutil.rmtree(out_folder)
-
-    pool = Pool(folder=folder)
-
-    pool.print_questions()
-    questions_set = QuestionSet(questions=pool.questions)  # type: ignore[arg-type]
-    number_of_questions = questions_set.size()
-    questions = questions_set.sample(n=number_of_questions)
-    exam_template = ExamTemplate.load(template_tex_path)
-
-    exam = Exam(
-        exam_template=exam_template,
-        questions=questions,
-        show_answers=show_answers,
-    )
-    exam.apply_shuffling(shuffle_questions=True, shuffle_answers=True)
-
-    result = exam.compile(path=out_folder, clean=clean)
-
-    print("STDOUT:")
-    print("\n\t".join(result.stdout.splitlines()))
-    print("STDERR:")
-    print("\n\t".join(result.stderr.splitlines()))