mcqpy-pdf 0.2.0__tar.gz

mcqpy_pdf-0.2.0/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.3
+Name: mcqpy-pdf
+Version: 0.2.0
+Summary: PDF compilation, parsing, and report rendering for MCQPy
+Author: Mads-Peter
+Author-email: Mads-Peter <machri@phys.au.dk>
+Requires-Dist: mcqpy-core[analysis,grading,yaml]>=0.1.1
+Requires-Dist: click>=8.3.0
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: pylatex>=1.4.2
+Requires-Dist: pylatexenc>=2.10
+Requires-Dist: pypdf>=6.1.1
+Requires-Dist: rich>=14.2.0
+Requires-Dist: rich-click>=1.9.3
+Requires-Dist: requests
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# mcqpy-pdf
+
+PDF compilation, parsing, and report rendering package for MCQPy.
+
+This package is built from its package-local source tree under `packages/mcqpy-pdf/src/mcqpy_pdf`.

mcqpy_pdf-0.2.0/README.md

@@ -0,0 +1,5 @@
+# mcqpy-pdf
+
+PDF compilation, parsing, and report rendering package for MCQPy.
+
+This package is built from its package-local source tree under `packages/mcqpy-pdf/src/mcqpy_pdf`.

mcqpy_pdf-0.2.0/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "mcqpy-pdf"
+version = "0.2.0"
+description = "PDF compilation, parsing, and report rendering for MCQPy"
+readme = "README.md"
+authors = [
+    { name = "Mads-Peter", email = "machri@phys.au.dk" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "mcqpy-core[analysis,grading,yaml]>=0.1.1",
+    "click>=8.3.0",
+    "openpyxl>=3.1.5",
+    "pylatex>=1.4.2",
+    "pylatexenc>=2.10",
+    "pypdf>=6.1.1",
+    "rich>=14.2.0",
+    "rich-click>=1.9.3",
+    "requests",
+]
+
+[tool.uv.sources]
+mcqpy-core = { workspace = true }
+
+[build-system]
+requires = ["uv_build>=0.8.18,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root = "src"

mcqpy_pdf-0.2.0/src/mcqpy_pdf/__init__.py

@@ -0,0 +1,6 @@
+"""PDF-specific MCQPy functionality."""
+
+from .grader import grade_pdf
+from .parse_pdf import MCQPDFParser
+
+__all__ = ["MCQPDFParser", "grade_pdf"]

mcqpy_pdf-0.2.0/src/mcqpy_pdf/analysis/report.py

@@ -0,0 +1,168 @@
+import re
+from pathlib import Path
+
+from pylatex import (
+    Command,
+    Document,
+    Enumerate,
+    Figure,
+    LongTable,
+    MultiColumn,
+    NewPage,
+    NoEscape,
+    Package,
+    Section,
+)
+from rich.console import Console
+from rich.progress import track
+
+from mcqpy_pdf.cli.config import GradingConfig
+from mcqpy_pdf.compile.preamble import add_preamble
+from mcqpy_core.grading.types import GradedSet, get_grade_dataframe
+from mcqpy_core.question import QuestionBank
+from mcqpy_core.grading.analysis.question_analysis import question_analysis
+from mcqpy_core.grading.analysis.overall_analysis import make_quiz_analysis
+
+
+class QuizAnalysis(Document):
+    def __init__(
+        self,
+        graded_sets: list[GradedSet],
+        question_bank: QuestionBank,
+        output_dir: str | Path = None,
+        console: Console = None,
+        grading_config: GradingConfig | None = None,
+    ):
+        super().__init__(
+            documentclass="article",
+            geometry_options={
+                "paper": "a4paper",
+                "includeheadfoot": True,
+                "left": "2cm",
+                "right": "3cm",
+                "top": "2.5cm",
+                "bottom": "2.5cm",
+            },
+        )
+        self.graded_sets = graded_sets
+        self.output_dir = Path(output_dir)
+        self.figure_directory = self.output_dir / "figures"
+        self.figure_directory.mkdir(parents=True, exist_ok=True)
+        self.console = console or Console()
+        self.question_bank = question_bank
+        self.grading_config = grading_config or GradingConfig()
+
+    def build(self):
+        # Added TOC
+        add_preamble(self)
+        self.preamble.append(Package("xcolor", options=["dvipsnames"]))
+        self.preamble.append(Command("title", "Quiz Analysis Report"))
+        self.preamble.append(Command("author", "MCQPy"))
+        self.preamble.append(Command("date", NoEscape(r"\today")))
+        self.append(NoEscape(r"\maketitle"))
+        self.append(NoEscape(r"\tableofcontents"))
+        self.append(NewPage())
+
+        self.console.log("Building quiz analysis...")
+        self.build_quiz_analysis()
+        self.console.log("Building question analysis...")
+        self.build_question_analyses()
+        self.console.log("Building grade table...")
+        self.build_grade_table()
+
+        self.console.log("Generating PDF...")
+        self.generate_pdf(self.output_dir / "quiz_analysis", clean_tex=True)
+        self.console.log("Finished generating PDF.")
+
+    def build_quiz_analysis(self):
+        figures = make_quiz_analysis(self.graded_sets, self.figure_directory)
+        with self.create(Section("Overall Quiz Analysis", numbering="0")):
+            for figure in figures:
+                with self.create(Figure(position="h!")) as fig:
+                    fig.add_image(
+                        (Path("figures") / figure.name).as_posix(),
+                        width=NoEscape(r"0.8\textwidth"),
+                    )
+                    fig.add_caption(NoEscape(figure.caption))
+
+        self.append(NoEscape(r"\clearpage"))
+        self.append(NewPage())
+
+    def build_question_analyses(self):
+        num_questions = len(self.graded_sets[0].graded_questions)
+        for q_index in track(
+            range(num_questions), description="Generating question analyses"
+        ):
+            with self.create(Section(f"Question {q_index + 1} Analysis")):
+                graded_questions = [
+                    gs.graded_questions[q_index] for gs in self.graded_sets
+                ]
+
+                figures = question_analysis(
+                    graded_questions=graded_questions,
+                    graded_sets=self.graded_sets,
+                    out_directory=self.figure_directory,
+                )
+
+                question = self.question_bank.get_by_qid(graded_questions[0].qid)
+
+                self.append(NoEscape(question.text))
+
+                with self.create(
+                    Enumerate(enumeration_symbol=r"(\alph*)", options={})
+                ) as enum:
+                    for choice in question.choices:
+                        enum.add_item(NoEscape(choice))
+
+                for figure in figures:
+                    with self.create(Figure(position="h!")) as fig:
+                        self.append(NoEscape(r"\centering"))
+                        fig.add_image(
+                            (Path("figures") / figure.name).as_posix(), width=NoEscape(r"0.8\textwidth")
+                        )
+                        fig.add_caption(
+                            f"Analysis for Question {q_index + 1}: {figure.caption}"
+                        )
+
+                self.append(NewPage())
+
+    def build_grade_table(self):
+        df = get_grade_dataframe(
+            self.graded_sets, sort_key=self.grading_config.output_sort_key
+        )
+
+        keys = []
+
+        for key in df.keys().tolist():
+            if re.match(r"Q\d+_points", key) or key in ["max_points"]:
+                continue
+            keys.append(key)
+
+        with self.create(Section("Grade Summary Table")):
+            with self.create(LongTable("l" * len(keys))) as data_table:
+                data_table.add_hline()
+                data_table.add_row(keys)
+                data_table.add_hline()
+                data_table.end_table_header()
+                data_table.add_hline()
+                data_table.add_row(
+                    (MultiColumn(len(keys), align="r", data="Continued on Next Page"),)
+                )
+                data_table.add_hline()
+                data_table.end_table_footer()
+                data_table.add_hline()
+                data_table.add_row(
+                    (
+                        MultiColumn(
+                            len(keys), align="r", data="Not Continued on Next Page"
+                        ),
+                    )
+                )
+                data_table.add_hline()
+                data_table.end_table_last_footer()
+
+                for row in df.itertuples(index=False):
+                    row_data = []
+                    for key in keys:
+                        row_data.append(getattr(row, key))
+                    data_table.add_row(row_data)

mcqpy_pdf-0.2.0/src/mcqpy_pdf/cli/__init__.py

@@ -0,0 +1,24 @@
+"""Command registration for mcqpy-pdf."""
+
+from mcqpy_pdf.cli.main import main
+from mcqpy_pdf.cli.build import build_command
+from mcqpy_pdf.cli.check_latex import check_latex_command
+from mcqpy_pdf.cli.grade import grade_command
+from mcqpy_pdf.cli.utils.autofill import autofill_command
+from mcqpy_pdf.cli.utils.main import utils_group
+
+
+def register_pdf_commands(parent) -> None:
+    for name, command in main.commands.items():
+        parent.add_command(command, name)
+
+
+__all__ = [
+    "register_pdf_commands",
+    "main",
+    "build_command",
+    "grade_command",
+    "check_latex_command",
+    "utils_group",
+    "autofill_command",
+]

mcqpy_pdf-0.2.0/src/mcqpy_pdf/cli/_selection.py

@@ -0,0 +1,31 @@
+"""Shared question-selection helpers for CLI commands."""
+
+from __future__ import annotations
+
+from mcqpy_pdf.cli.config import SelectionConfig
+from mcqpy_core.question import QuestionBank
+from mcqpy_core.question.filter import FilterFactory
+
+
+def _build_filter(filter_name: str, filter_params: dict):
+    filter_config = {"type": filter_name, **filter_params}
+    return FilterFactory.from_config(filter_config)
+
+
+def build_filters(selection_config: SelectionConfig):
+    filter_objs = []
+    if selection_config.filters:
+        for filter_name, filter_params in selection_config.filters.items():
+            filter_objs.append(_build_filter(filter_name, filter_params))
+    return filter_objs
+
+
+def select_questions(question_bank: QuestionBank, selection_config: SelectionConfig):
+    for filter_obj in build_filters(selection_config):
+        question_bank.add_filter(filter_obj)
+
+    return question_bank.get_filtered_questions(
+        number_of_questions=selection_config.number_of_questions,
+        shuffle=selection_config.shuffle,
+        sorting=selection_config.sort_type,
+    )

mcqpy_pdf-0.2.0/src/mcqpy_pdf/cli/build.py

@@ -0,0 +1,89 @@
+"""
+CLI Build Command
+"""
+
+from pathlib import Path
+
+import rich_click as click
+from rich.pretty import Pretty
+from rich.console import Console
+
+from mcqpy_pdf.cli._selection import select_questions, _build_filter, build_filters
+from mcqpy_pdf.cli.config import QuizConfig
+from mcqpy_pdf.cli.main import main
+from mcqpy_pdf.compile import MultipleChoiceQuiz
+from mcqpy_pdf.compile.manifest import Manifest
+from mcqpy_core.question import QuestionBank
+
+
+# Backward-compatible private alias kept for older tests/importers.
+_select_questions = select_questions
+
+
+def build_solution(questions, manifest, output_path: Path):
+    from mcqpy_pdf.compile.solution_pdf import SolutionPDF
+
+    solution_pdf = SolutionPDF(file=output_path, questions=questions, manifest=manifest)
+    solution_pdf.build(generate_pdf=True)
+
+@main.command(
+    name="build",
+    help="""Build the quiz PDF from question files based on the provided configuration.
+    This command reads the quiz configuration, selects questions from the question bank,
+    and generates the quiz PDF along with a solution PDF.
+""",
+)
+@click.option(
+    "-c",
+    "--config",
+    type=click.Path(exists=True, path_type=Path),
+    default="config.yaml",
+    help="Path to the config file",
+    show_default=True,
+)
+def build_command(config):
+    """ 
+    Build the quiz PDF from question files based on the provided configuration.
+    This command reads the quiz configuration, selects questions from the question bank,
+    and generates the quiz PDF along with a solution PDF.
+
+    ```
+    mcqpy build --config config.yaml
+    ```
+    """
+
+    config = QuizConfig.read_yaml(config)
+    question_bank = QuestionBank.from_directories(
+        config.questions_paths, seed=config.selection.seed, progress_bar=True
+    )
+    questions = select_questions(question_bank, config.selection)
+
+    console = Console()
+    console.print("[bold green]Quiz Configuration:[/bold green]")
+    console.print(Pretty(config))
+    console.print(
+        f"[bold green]Total questions in bank:[/bold green] {len(question_bank)}"
+    )
+    console.print(f"[bold green]Selected questions:[/bold green] {len(questions)}")
+
+    ## Paths:
+    for path in [config.root_directory, config.output_directory, config.submission_directory]:
+        if path and not path.exists():
+            path.mkdir(parents=True, exist_ok=True)  # pragma: no cover
+
+    mcq = MultipleChoiceQuiz(
+        file=config.file_path,
+        questions=questions,
+        front_matter=config.front_matter,
+        header_footer=config.header,
+    )
+
+    mcq.build(generate_pdf=True)
+
+    # Build solution PDF
+    manifest_path = mcq.get_manifest_path()
+    manifest = Manifest.load_from_file(manifest_path)
+    solution_output_path = (
+        config.output_directory / f"{config.file_name.replace('.pdf', '')}_solution.pdf"
+    )
+    build_solution(questions, manifest, solution_output_path)

mcqpy_pdf-0.2.0/src/mcqpy_pdf/cli/check_latex.py

@@ -0,0 +1,31 @@
+"""
+CLI command to check LaTeX installation and configuration.
+"""
+
+from mcqpy_pdf.cli.main import main
+
+@main.command('check-latex', help="Check LaTeX installation and configuration.")
+def check_latex_command():
+    """
+    Check if LaTeX is installed and properly configured. 
+    Provides the CLI command:
+    ```
+    mcqpy check-latex
+    ```
+    This command verifies the presence of LaTeX tools such as `pdflatex` and `latexmk`,
+    and attempts to compile a simple LaTeX document to ensure everything is functioning correctly.
+    """
+
+    from mcqpy_pdf.utils.check_latex import check_latex_installation
+    from rich.console import Console
+    
+    console = Console()    
+    success, details = check_latex_installation()
+    
+    if success:
+        console.print("[bold green]✓ LaTeX is properly installed![/bold green]")
+        console.print(f"[green]pdflatex version[/green]: {details['pdflatex'].version}")
+        console.print(f"[green]latexmk version[/green]: {details['latexmk'].version}")
+        console.print("[green]Compilation test passed successfully.[/green]")
+    else:
+        console.print(f"[bold red]✗ LaTeX installation issue: {details['error_message']}[/bold red]")

mcqpy_pdf-0.2.0/src/mcqpy_pdf/cli/config.py

@@ -0,0 +1,154 @@
+"""
+Quiz configuration management using Pydantic and YAML.
+"""
+
+from pydantic import BaseModel, Field, ConfigDict, field_validator, model_validator
+import yaml
+from mcqpy_pdf.compile import HeaderFooterOptions, FrontMatterOptions
+from typing import Any, Literal
+from pathlib import Path
+
+
+class GradingConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid", validate_assignment=True)
+    submission_directory: str = Field(
+        default="submissions", description="Directory for student submissions relative to quiz root directory"
+    )
+    anonymous_pattern: str | None = Field(
+        default=None,
+        description="Regex pattern to extract identifiers from anonymous exam filenames (e.g., 'exam_(?P<id1>\\w+)_(?P<id2>\\w+)\\.pdf')",
+    )
+    output_sort_key: str | None = Field(
+        default=None,
+        description="Key to sort output files, e.g., 'student_name' or 'student_id' or one based on the anonymous pattern",
+    )
+
+    @field_validator("anonymous_pattern")
+    @classmethod
+    def validate_pattern(cls, v):
+        """Validate that the pattern is a valid regex"""
+        if v is not None:
+            import re
+
+            try:
+                re.compile(v)
+            except re.error as e:
+                raise ValueError(f"Invalid regex pattern: {e}")
+        return v
+
+
+class SelectionConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid", validate_assignment=True)
+    number_of_questions: int | None = Field(
+        default=20, description="Number of questions to select"
+    )
+    filters: dict[str, dict[str, Any]] | None = Field(
+        default=None, description="Filters to apply when selecting questions"
+    )
+    seed: int | None = Field(
+        default=None, description="Random seed for question selection"
+    )
+    shuffle: bool = Field(
+        default=False, description="Whether to shuffle selected questions"
+    )
+    sort_type: Literal["slug", "none"] = Field(
+        default="none", description="Sort type for selected questions"
+    )
+
+
+class QuizConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid", validate_assignment=True, populate_by_name=True)
+    questions_paths_: list[str] | str = Field(
+        default=["questions"], description="Paths to question files or directories, relative to the config file's directory", alias="questions_paths"
+    )
+    file_name: str = Field(
+        default="quiz.pdf", description="Name of the output PDF file"
+    )
+    
+    root_directory_: str = Field(
+        default=".", description="Root directory for the quiz project, relative to the location of the config file", 
+        alias="root_directory"
+    )
+    output_directory_: str = Field(
+        default="output", description="Directory for output files, relative to the root directory", alias="output_directory"
+    )
+    grading: GradingConfig = Field(default_factory=GradingConfig)
+    front_matter: FrontMatterOptions = Field(default_factory=FrontMatterOptions)
+    header: HeaderFooterOptions = Field(default_factory=HeaderFooterOptions)
+    selection: SelectionConfig = Field(default_factory=SelectionConfig)
+    path: Path | None = Field(None, description="Internal: file path from which the config was loaded", exclude=True)
+
+    @property
+    def root_directory(self) -> Path:
+        """Get root directory as a Path object"""
+        return (Path(self.path).parent / self.root_directory_).resolve()
+    
+    @property
+    def output_directory(self) -> Path:
+        """Get output directory as a Path object"""
+        return self.root_directory / self.output_directory_
+
+    @property
+    def questions_paths(self) -> list[Path]:
+        """Get questions paths as Path objects"""
+        return [(self.path.parent / p).resolve() for p in self.questions_paths_]
+    
+    @property
+    def file_path(self) -> Path:
+        """Get full file path for the output PDF"""
+        return self.output_directory / self.file_name
+    
+    @property
+    def submission_directory(self) -> Path:
+        """Get submission directory as a Path object"""
+        return self.root_directory / self.grading.submission_directory
+    
+
+    @model_validator(mode="before")
+    @classmethod
+    def migrate_submission_directory(cls, data):
+        """Migrate submission_directory from top level to grading config"""
+        if isinstance(data, dict) and "submission_directory" in data:
+            if "grading" not in data:
+                data["grading"] = {}
+            data["grading"]["submission_directory"] = data.pop("submission_directory")
+        return data
+    
+    @model_validator(mode="before")
+    def check_paths_exist(cls, data):
+        """Resolve questions_paths relative to the config file's directory"""
+        path = data.get("path")
+        if not path:
+            return data
+        
+        config_dir = path.parent
+        
+        # Questions:
+        paths_to_check = data.get("questions_paths", []) + data.get("questions_paths_", [])
+        for path in paths_to_check:
+            resolved_path = (config_dir / path).resolve()
+            if not resolved_path.exists():
+                raise FileNotFoundError(f"Questions path does not exist: {resolved_path}")
+
+        return data
+
+    def yaml_dump(self) -> str:
+        """Dump the current configuration to a YAML string"""
+        config_dict = self.model_dump(by_alias=True)
+        yaml_content = yaml.dump(config_dict, default_flow_style=False, sort_keys=False)
+        return yaml_content
+
+    @classmethod
+    def generate_example_yaml(cls) -> str:
+        """Generate example YAML with comments"""
+        example = cls()
+        return example.yaml_dump()
+
+    @classmethod
+    def read_yaml(cls, file_path: str) -> "QuizConfig":
+        """Read YAML file and return a QuizConfig instance"""
+        with open(file_path, "r") as file:
+            yaml_string = file.read()
+        data = yaml.safe_load(yaml_string)
+        data['path'] = Path(file_path).resolve()
+        return cls(**data)

mcqpy_pdf-0.2.0/src/mcqpy_pdf/cli/export/__init__.py

@@ -0,0 +1,12 @@
+"""Export command registrations."""
+
+from .main import export_group
+from .token import decode_token_command, encode_token_command
+from .web import export_web_command
+
+__all__ = [
+    "export_group",
+    "encode_token_command",
+    "decode_token_command",
+    "export_web_command",
+]

mcqpy_pdf-0.2.0/src/mcqpy_pdf/cli/export/main.py

@@ -0,0 +1,11 @@
+"""CLI group for web export utilities."""
+
+import rich_click as click
+
+from mcqpy_pdf.cli.main import main
+
+
+@main.group(name="export")
+def export_group() -> None:
+    """Commands for exporting browser-ready quiz artifacts."""
+    return None  # pragma: no cover

mcqpy_pdf-0.2.0/src/mcqpy_pdf/cli/export/token.py

@@ -0,0 +1,20 @@
+"""CLI helpers for quiz link obfuscation tokens."""
+
+from __future__ import annotations
+
+import rich_click as click
+
+from mcqpy_pdf.cli.export.main import export_group
+from mcqpy_core.web import decode_quiz_token, encode_quiz_token
+
+
+@export_group.command(name="encode-token", help="Encode a public quiz bundle URL.")
+@click.argument("url")
+def encode_token_command(url: str) -> None:
+    click.echo(encode_quiz_token(url))
+
+
+@export_group.command(name="decode-token", help="Decode a quiz token to its public URL.")
+@click.argument("token")
+def decode_token_command(token: str) -> None:
+    click.echo(decode_quiz_token(token))