randex 0.1.0__tar.gz → 0.2.0__tar.gz

{randex-0.1.0 → randex-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: randex
-Version: 0.1.0
+Version: 0.2.0
 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.1.0 → randex-0.2.0}/README.md

@@ -13,16 +13,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.
@@ -31,41 +35,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}
@@ -91,7 +141,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:
 
@@ -99,62 +149,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.1.0 → randex-0.2.0}/pyproject.toml

@@ -53,7 +53,7 @@ packages = [
   {include = "scripts"}
 ]
 readme = "README.md"
-version = "0.1.0"
+version = "0.2.0"
 
 [tool.poetry.dependencies]
 cerberus = "^1.3.5"
@@ -77,6 +77,7 @@ 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"
 
 [tool.poetry.urls]

randex-0.2.0/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()