randex 0.1.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

randex/cli.py

@@ -0,0 +1,56 @@
+"""Shared CLI utilities for randex scripts."""
+
+import click
+
+
+class CustomCommand(click.Command):
+    """Custom Click command that provides better error messages."""
+
+    def parse_args(
+        self,
+        ctx: click.Context,
+        args: list[str],
+    ) -> list[str]:
+        """
+        Override parse_args to catch parameter parsing errors.
+
+        This is a workaround to catch the error when the user passes multiple
+        folder arguments to the command.
+
+        Parameters
+        ----------
+        ctx : click.Context
+            The click context.
+        args : list[str]
+            The arguments passed to the command.
+
+        Returns
+        -------
+        list[str]:
+            The remaining unparsed arguments.
+
+        Examples
+        --------
+        ```bash
+        exams examples/en/folder_* -t template.yaml -n 2
+        ```
+        """
+        try:
+            return super().parse_args(ctx, args)
+        except click.UsageError as e:
+            if "Got unexpected extra arguments" in str(e):
+                # Extract the extra arguments from the error message
+                error_msg = str(e)
+                if "(" in error_msg and ")" in error_msg:
+                    extra_args = error_msg.split("(")[1].split(")")[0]
+
+                    raise click.UsageError(
+                        f"❌ Multiple folder arguments detected: {extra_args}\n\n"
+                        f"💡 This usually happens when your shell expands a glob pattern like 'examples/en/folder_*'\n"  # noqa: E501
+                        f"   into multiple folder names before passing them to the command.\n\n"  # noqa: E501
+                        f"🔧 Solutions:\n"
+                        f'   • Put quotes around your glob pattern: "examples/en/folder_*"\n'  # noqa: E501
+                        f"   • Or specify a single folder path instead of a glob pattern\n\n"  # noqa: E501
+                        f'Example: exams "examples/en/folder_*" -t template.yaml -n 2'
+                    ) from e
+            raise

randex/exam.py

@@ -202,8 +202,14 @@ class Pool:
             matched = [p.resolve() for p in Path().glob(folder_input) if p.is_dir()]
             if not matched:
                 raise ValueError(
-                    f"'{folder_input}' was detected as a glob pattern but "
-                    "matched no folders. If this is a folder name, use a Path instead.",
+                    f"❌ No folders found matching the pattern: '{folder_input}'\n\n"
+                    f"💡 Suggestions:\n"
+                    f"   • Check if the path exists and contains folders\n"
+                    f"   • Verify the spelling (common mistake: 'example' vs 'examples')\n"  # noqa: E501
+                    f"   • Use quotes around the pattern to prevent shell expansion\n"
+                    f"   • Try listing the directory to see available folders\n\n"
+                    f"🔍 If '{folder_input}' is meant to be a literal folder name (not a pattern), "  # noqa: E501
+                    f"remove the special characters or use a Path object instead."
                 )
             return matched
 

{randex-0.1.0.dist-info → randex-0.2.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: randex
-Version: 0.1.0
+Version: 0.2.1
 Summary: Create randomized multiple choice exams using latex.
 License: CC BY-NC 4.0
 Author: G. Arampatzis
@@ -39,16 +39,20 @@ Multiple exams can be created at once.
 
 ## Installation
 
-Randex requires Python version `3.10` or higher, `Poetry`, and `latexmk`.
+Randex requires Python version `3.10` or higher and `latexmk`.
 
-### Poetry
+### Randex
+
+To install Randex, run the following command from the root folder of the project:
 
-[Poetry](https://python-poetry.org) is the packaging and dependency manager used for
-this project.
-To install Poetry, follow the instructions [here](https://python-poetry.org/docs/#installing-with-pipx).
+```sh
+pip install randex
+```
 
 ### latexmk
 
+In order to compile the LaTeX files, you need to install `latexmk`,
+
 From [here](https://mg.readthedocs.io/latexmk.html):
 ```
 Latexmk is a Perl script which you just have to run once and it does everything else for you... completely automagically.
@@ -57,41 +61,87 @@ Latexmk is a Perl script which you just have to run once and it does everything
 and [here](https://www.cantab.net/users/johncollins/latexmk/)
 
 ```
-Latexmk is also available at CTAN at https://ctan.org/pkg/latexmk/, and is/will be in the TeXLive and MiKTeX distributions.
+Latexmk is also available at CTAN at https://ctan.org/pkg/latexmk/, and is/will be
+in the TeXLive and MiKTeX distributions.
 ```
 
 If you have already `Latex` installed in your system, you will most
 probably have already `latexmk` installed as well.
 
-### Randex
+## Randex Commands
 
-To install Randex, run the following command from the root folder of the project:
+### randex-download-examples
+
+To download the latest examples from GitHub, run the following command from the root
+folder of the project:
+
+```sh
+randex-download-examples
+```
+
+### 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_*"
+```
+
+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 `--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.
+
+Run:
 
 ```sh
-poetry install
+validate --help
 ```
 
-Then execute:
+to see the help message for the command.
+
+### exams
+
+To create a batch of exams with random questions, execute:
 
 ```sh
-poetry shell
+exams -b 5 -n 2 -t examples/en/template-exam.yaml -o tmp --overwrite --clean "examples/en/folder_*"
 ```
 
-to spawn a shell with the Python environment activated.
+This command will create 5 exams from 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
+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.
+
+### Grade
+
+Not implemented yet.
 
 ## Randex Data Scheme
 
 Randex requires two types of data files to create the exams.
 
-### Tex File
+### template-exam.yaml File
 
-The `Tex` file is a `YAML` file that describes the LaTeX file that will produce the exam. It contains the following keys:
+The `template-exam.yaml` file is a `YAML` file that describes the LaTeX file that will
+produce the exam. It contains the following keys:
 
-- `documentclass` (optional): String with the documentclass command of the file. Only the `exam` class is supported. Default:
+- `documentclass` (optional): String with the documentclass command of the file.
+Only the `exam` class is supported. Default:
     ```latex
     \documentclass[11pt]{exam}
     ```
-- `prebegin` (optional): String containing everything that goes before the `\begin{document}` command. Default:
+- `prebegin` (optional): String containing everything that goes before the
+`\begin{document}` command. Default:
     ```latex
     \usepackage{amsmath}
     \usepackage{amssymb}
@@ -117,7 +167,7 @@ The `Tex` file is a `YAML` file that describes the LaTeX file that will produce
 
 The right part of the head is reserved for the serial number of the exam.
 
-### Questions File
+### questions.yaml File
 
 Each question is written in a `YAML` file with the following keys:
 
@@ -125,62 +175,11 @@ Each question is written in a `YAML` file with the following keys:
 - `answers` (required): List of strings with the answers. Do not use double quotes around the strings.
 - `right_answer` (required): Integer indicating the correct answer.
 The answer is non-negative and less than the length of the `answers` list.
-- `points` (optional): Points given to the question. Default: `1`
 
 The questions `YAML` files should be organized inside folders.
 
-The `randex` commands take the `Tex` file and the folders containing the exams as inputs.
-
-## Randex Commands
-
-Inside an activated environment, you can run the following commands.
-
-### Validate
+The `randex` commands take the `template-exam.yaml` file and the folders containing the questions as inputs.
 
-This command validates a single question or all questions inside a folder. Execute:
-
-```sh
-validate example/en -t example/en/tex.yaml -o temp --clean -a
-```
-
-to validate all the questions inside the folder `example/en` that contains subfolders
-with questions.
-It will use the configuration from the file `example/en/tex.yaml`.
-The LaTeX compilation will run inside the `temp` 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.
-
-Run:
-
-```sh
-validate --help
-```
-
-to see the help message for the command.
-
-### Exams
-
-To create a batch of exams with random questions, execute:
-
-```sh
-exams example/en/folder_0/ example/en/folder_1/ example/en/folder_2/ -b 10 -t example/en/tex.yaml --clean -n 2
-```
-
-This command will create 10 exams from 3 folders using the configuration from the file
-`example/en/tex.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`, indicating the first folder will contribute
-2 questions, and the remaining folders will contribute 1 question each.
-For example, `-n 2 -n 1 -n 3` means the first, second,
-and third folders will contribute 2, 1, and 3 questions, respectively.
-The `-b` option specifies the number of exams to create.
-
-### Grade
-
-Not implemented yet.
 
 
 # License

randex-0.2.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+randex/__init__.py,sha256=6bBAISO6MqVCSCvqLcK3SGUnDODuwobLWouO3GY8SRU,187
+randex/cli.py,sha256=hwLgZIfBkAeFXlbveywmQlKBGz9GsD_P6Q89YSDOe2M,2039
+randex/exam.py,sha256=sYBQhYjmZDNyTicSD6nOOTo_7c_rst5rhyjCJhCbVtk,26975
+scripts/__init__.py,sha256=F8pjiW8AlL0IhnvVh1TEfgiD--YdFE_PggtSevHp5y4,38
+scripts/exams.py,sha256=D4ky-3J4yx7R3_-UgpGT7C9nQWFqNvdn-fhvzt9Jkbg,3401
+scripts/randex_download_examples.py,sha256=fj88XkZV8bpHPCeXu1f3nVNws_hbcJ_3Zso7XOPB0RQ,1682
+scripts/validate.py,sha256=MnJqfSs8n6qSuxMUT4W0P4ePGyDtRUIXKakWVy20eVo,2659
+randex-0.2.1.dist-info/LICENSE,sha256=NxH5Y8BdC-gNU-WSMwim3uMbID2iNDXJz7fHtuTdXhk,19346
+randex-0.2.1.dist-info/METADATA,sha256=18RJ4FY6RmVK4C9OxDWM8Qe8kY0SClXtbnXT8VrRYP8,6551
+randex-0.2.1.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+randex-0.2.1.dist-info/entry_points.txt,sha256=RayNUArGNT0MLZi7uh1MHjnd1L1V4X6C4sBdMLbvAfc,138
+randex-0.2.1.dist-info/RECORD,,

{randex-0.1.0.dist-info → randex-0.2.1.dist-info}/entry_points.txt

@@ -1,4 +1,5 @@
 [console_scripts]
 exams=scripts.exams:main
+randex-download-examples=scripts.randex_download_examples:main
 validate=scripts.validate:main
 

scripts/exams.py

@@ -6,10 +6,12 @@ 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(

scripts/randex_download_examples.py

@@ -0,0 +1,57 @@
+"""Download the latest examples from GitHub."""
+
+import io
+import shutil
+import sys
+import tempfile
+import urllib.request
+import zipfile
+from pathlib import Path
+from urllib.error import URLError
+
+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...")
+
+    if DEST_DIR.exists():
+        print(
+            f"❌ Destination folder '{DEST_DIR}' already exists. "
+            "Please remove it first."
+        )
+        sys.exit(1)
+
+    try:
+        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())
+            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.")
+                sys.exit(1)
+
+            examples_path = root_entry / "examples"
+
+            if not examples_path.exists():
+                print("❌ examples/ folder not found in the downloaded repository.")
+                sys.exit(1)
+
+            shutil.copytree(examples_path, DEST_DIR)
+            print(f"✅ Examples downloaded to: {DEST_DIR.resolve()}")
+
+    except (URLError, zipfile.BadZipFile, OSError, shutil.Error) as e:
+        print(f"❌ Error: {e}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

scripts/validate.py

@@ -6,10 +6,12 @@ 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(

randex-0.1.0.dist-info/RECORD

@@ -1,10 +0,0 @@
-randex/__init__.py,sha256=6bBAISO6MqVCSCvqLcK3SGUnDODuwobLWouO3GY8SRU,187
-randex/exam.py,sha256=l-_6GnrstLgVMORXNEIKzgW9k6h_YbXndZd8YmEGKBI,26450
-scripts/__init__.py,sha256=F8pjiW8AlL0IhnvVh1TEfgiD--YdFE_PggtSevHp5y4,38
-scripts/exams.py,sha256=L4QSOZpU8Hw5QkW_2x5s8NESQAwlEmZTSaT6ZZ8-c04,3341
-scripts/validate.py,sha256=xruN1P1rgJnc0MTklLgSrsx9TcFC2SY1a9eksNT_-KM,2599
-randex-0.1.0.dist-info/LICENSE,sha256=NxH5Y8BdC-gNU-WSMwim3uMbID2iNDXJz7fHtuTdXhk,19346
-randex-0.1.0.dist-info/METADATA,sha256=7UQ_rkrBEjHg9pKOjqMKrSRcv4S8FjjGLS7zgmEmG-g,6677
-randex-0.1.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
-randex-0.1.0.dist-info/entry_points.txt,sha256=gRD7WCYtG4hW2sv_mg2TT7ifbCGjqNqMBezaUa32F64,75
-randex-0.1.0.dist-info/RECORD,,