mcqpy 0.1.0__py3-none-any.whl

mcqpy/__init__.py

@@ -0,0 +1,2 @@
+from .question import Question
+

mcqpy/cli/__init__.py

@@ -0,0 +1,7 @@
+from mcqpy.cli.main import main
+from mcqpy.cli.init import init_command
+from mcqpy.cli.build import build_command
+from mcqpy.cli.grade import grade_command
+from mcqpy.cli.autofill import autofill_command
+from mcqpy.cli.question import question_group
+from mcqpy.cli.check_latex import check_latex_command

mcqpy/cli/autofill.py

@@ -0,0 +1,56 @@
+import contextlib
+import io
+from pathlib import Path
+
+import rich_click as click
+from rich.progress import track
+
+from mcqpy.cli.config import QuizConfig
+from mcqpy.cli.main import main
+from mcqpy.compile.manifest import Manifest
+from mcqpy.utils.fill_form import fill_pdf_form
+
+
+@main.command(
+    name="test-autofill",
+    help="Make answered versions of quiz to test mcqpy functionality",
+)
+@click.option(
+    "-c",
+    "--config",
+    type=click.Path(exists=True, path_type=Path),
+    default="config.yaml",
+    help="Path to the config file",
+    show_default=True,
+)
+@click.option(
+    "-n",
+    "--num-forms",
+    type=int,
+    default=10,
+    help="Number of filled forms to generate",
+    show_default=True,
+)
+@click.option('--correct', is_flag=True, help="Fill forms with correct answers")
+def autofill_command(config, num_forms, correct):
+    # Directories & files
+    config = QuizConfig.read_yaml(config)
+    file_path = Path(config.output_directory) / config.file_name
+    output_dir = Path(config.submission_directory)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    file_name = Path(config.file_name).stem
+    manifest_path = Path(config.output_directory) / f"{file_name}_manifest.json"
+    manifest = Manifest.load_from_file(manifest_path)
+
+    # In the autofill_command function
+    for i in track(range(num_forms), description="Generating filled forms..."):
+        stdout_capture = io.StringIO()
+        stderr_capture = io.StringIO()
+
+        with (
+            contextlib.redirect_stdout(stdout_capture),
+            contextlib.redirect_stderr(stderr_capture),
+        ):
+            fill_pdf_form(file_path, out_path=output_dir, index=i, manifest=manifest, correct_only=correct)
+
+    click.echo(f"Generated {num_forms} filled forms based on {file_path}")

mcqpy/cli/build.py

@@ -0,0 +1,88 @@
+import rich_click as click
+import numpy as np
+from mcqpy.cli.main import main
+from mcqpy.cli.config import QuizConfig, SelectionConfig
+from pathlib import Path
+from mcqpy.question.filter import FilterFactory
+
+from mcqpy.compile import MultipleChoiceQuiz
+from mcqpy.question import QuestionBank
+from mcqpy.compile.manifest import Manifest
+
+from rich.pretty import Pretty
+from rich.console import Console
+
+
+def build_solution(questions, manifest, output_path: Path):
+    from mcqpy.compile.solution_pdf import SolutionPDF
+    solution_pdf = SolutionPDF(file=output_path, questions=questions, manifest=manifest)
+    solution_pdf.build(generate_pdf=True)
+
+
+def _select_questions(question_bank: QuestionBank, selection_config: SelectionConfig):
+    ## Setup filters:
+    if selection_config.filters:
+        filter_objs = []
+        for filter_name, filter_params in selection_config.filters.items():
+            filter_config = {"type": filter_name, **filter_params}
+            filter_obj = FilterFactory.from_config(filter_config)
+            filter_objs.append(filter_obj)
+            question_bank.add_filter(filter_obj)
+
+    ## Apply filters and select questions
+    questions = question_bank.get_filtered_questions(
+        number_of_questions=selection_config.number_of_questions,
+        shuffle=selection_config.shuffle,
+        sorting=selection_config.sort_type,
+    )
+    return questions
+
+
+@main.command(name="build", help="Build the quiz PDF from question files")
+@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):
+    config = QuizConfig.read_yaml(config)
+    question_bank = QuestionBank.from_directories(config.questions_paths, seed=config.selection.seed)
+    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:
+    root = Path(config.root_directory)
+    output_dir = root / config.output_directory
+    file_path = output_dir / config.file_name
+    submission_dir = (
+        root / config.submission_directory if config.submission_directory else None
+    )
+
+    for path in [root, output_dir, submission_dir]:
+        if path and not path.exists():
+            path.mkdir(parents=True, exist_ok=True) # pragma: no cover
+
+    mcq = MultipleChoiceQuiz(
+        file=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 = (
+        output_dir / f"{config.file_name.replace('.pdf', '')}_solution.pdf"
+    )
+    build_solution(questions, manifest, solution_output_path)

mcqpy/cli/check_latex.py

@@ -0,0 +1,18 @@
+from mcqpy.cli import main
+
+@main.command('check-latex', help="Check LaTeX installation and configuration.")
+def check_latex_command():
+    from mcqpy.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/cli/config.py

@@ -0,0 +1,43 @@
+from pydantic import BaseModel, Field, ConfigDict
+import yaml
+from mcqpy.compile import HeaderFooterOptions, FrontMatterOptions
+from typing import Any, Literal
+
+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)
+    questions_paths: list[str] | str = Field(default=["questions"], description="Paths to question files or directories")
+    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")
+    output_directory: str = Field(default="output", description="Directory for output files")
+    submission_directory: str | None = Field(default=None, description="Directory for submission files (if any)")
+    front_matter: FrontMatterOptions = Field(default_factory=FrontMatterOptions)
+    header: HeaderFooterOptions = Field(default_factory=HeaderFooterOptions)
+    selection: SelectionConfig = Field(default_factory=SelectionConfig)
+
+    def yaml_dump(self) -> str:
+        """Dump the current configuration to a YAML string"""
+        config_dict = self.model_dump()
+        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)
+        return cls(**data)

mcqpy/cli/grade.py

@@ -0,0 +1,51 @@
+import rich_click as click
+from mcqpy.cli.main import main
+from mcqpy.cli.config import QuizConfig
+from pathlib import Path
+
+from mcqpy.grade import MCQGrader, get_grade_dataframe
+from mcqpy.compile.manifest import Manifest
+from mcqpy.grade.rubric import StrictRubric
+from rich.progress import track
+
+from mcqpy.question.question_bank import QuestionBank
+
+
+@main.command(name="grade", help="Grade student submissions")
+@click.option("-c", "--config", type=click.Path(exists=True, path_type=Path), default="config.yaml", help="Path to the config file", show_default=True)
+@click.option("-v", "--verbose", is_flag=True, help="Enable verbose output")
+@click.option("-f", "--file-format", type=click.Choice(["xlsx", "csv"]), default="xlsx", help="Output format for the grades", show_default=True)
+@click.option('-a', '--analysis', is_flag=True, help="Generate question analysis reports", default=False)
+def grade_command(config, verbose: bool, file_format: str, analysis: bool):
+
+    # Load config
+    config = QuizConfig.read_yaml(config)
+    file_name = Path(config.file_name).stem
+    manifest_path = Path(config.output_directory) / f"{file_name}_manifest.json"
+    manifest = Manifest.load_from_file(manifest_path)
+
+    # Read & Grade submissions
+    graded_sets = []    
+    submissions = list(Path(config.submission_directory).glob("*.pdf"))
+    for submission in track(submissions, description=f"Grading submissions ({len(submissions)})", total=len(submissions)):
+        grader = MCQGrader(manifest, StrictRubric())
+        graded_set = grader.grade(submission)
+        graded_sets.append(graded_set)
+
+    # Export grades to dataframe
+    df = get_grade_dataframe(graded_sets)
+    output_path = Path(config.submission_directory).parent / f"{file_name}_grades.{file_format}"
+    if file_format == "xlsx":
+        df.to_excel(output_path, index=False)
+    elif file_format == "csv":
+        df.to_csv(output_path, index=False)
+
+    if analysis:
+        from mcqpy.grade.analysis import QuizAnalysis
+        analysis_directory = Path('analysis/')
+        analysis_directory.mkdir(exist_ok=True)
+
+        question_bank = QuestionBank.from_directories(config.questions_paths)
+
+        quiz_analysis = QuizAnalysis(graded_sets, question_bank=question_bank, output_dir=analysis_directory)
+        quiz_analysis.build()

mcqpy/cli/init.py

@@ -0,0 +1,76 @@
+import rich_click as click
+from mcqpy.cli.main import main
+from mcqpy.cli.config import QuizConfig
+
+from pathlib import Path
+
+
+@main.command(name="init", help="Initialize a new quiz project")
+@click.argument("name", type=str, help="The name of the quiz project")
+@click.option(
+    "-f",
+    "--file-name",
+    type=str,
+    default="quiz.pdf",
+    help="Name of the output PDF file",
+    show_default=True,
+)
+@click.option(
+    "-mqd",
+    "--make-questions-directory",
+    is_flag=True,
+    help="Create a questions directory",
+    default=True,
+)
+@click.option(
+    "-o",
+    "--output-directory",
+    type=str,
+    default="output",
+    help="Directory for output files",
+    show_default=True,
+)
+@click.option(
+    "-s",
+    "--submission-directory",
+    type=str,
+    default="submissions",
+    help="Directory for student submissions",
+    show_default=True,
+)
+def init_command(
+    name: str,
+    file_name: str,
+    make_questions_directory: bool,
+    output_directory: str,
+    submission_directory: str,
+):
+    # Create project directory
+    project_path = Path(name)
+    project_path.mkdir(parents=True, exist_ok=False)
+    print(f"Initialized quiz project at: {project_path}")
+
+    # Create questions directory if flag is set
+    if make_questions_directory:
+        questions_dir = project_path / "questions"
+        questions_dir.mkdir(parents=True, exist_ok=False)
+        print(f"Created questions directory at: {questions_dir}")
+
+    submission_directory_path = project_path / submission_directory
+    submission_directory_path.mkdir(parents=True, exist_ok=False)
+
+    # Create example config.yaml
+    config_file = project_path / "config.yaml"
+    config = QuizConfig(
+        questions_paths=["questions"],
+        file_name=file_name,
+        output_directory=output_directory,
+        submission_directory=submission_directory,
+    )
+    config_file.write_text(config.yaml_dump())
+    print(f"Created config file at: {config_file}")
+
+    # Output directory
+    output_dir = project_path / output_directory
+    output_dir.mkdir(parents=True, exist_ok=False)
+    print(f"Created output directory at: {output_dir}")

mcqpy/cli/main.py

@@ -0,0 +1,10 @@
+import rich_click as click
+
+@click.group(name="mcqpy")
+@click.version_option()
+def main() -> None:
+    """
+    Command line interface for mcqpy.
+    """
+    return None # pragma: no cover
+

mcqpy/cli/question/__init__.py

@@ -0,0 +1,4 @@
+from .main import question_group
+from .validate import validate_command
+from .init import init_command
+from .render import render_command

mcqpy/cli/question/init.py

@@ -0,0 +1,25 @@
+import rich_click as click
+
+
+from mcqpy.cli.question.main import question_group
+
+
+@question_group.command(name="init", help="Initialize question file.")
+@click.argument("path", type=click.Path(exists=False))
+def init_command(path):
+    from mcqpy.question import Question
+    from rich.console import Console
+    from rich.pretty import Pretty
+
+
+    # Get the yaml schema for a question
+    schema = Question.get_yaml_template()
+    # Write to the specified path
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(schema)
+    
+
+
+
+
+            

mcqpy/cli/question/main.py

@@ -0,0 +1,9 @@
+import rich_click as click
+from mcqpy.cli.main import main
+
+@main.group(name="question")
+def question_group() -> None:
+    """
+    Commands related to question management.
+    """
+    return None # pragma: no cover

mcqpy/cli/question/render.py

@@ -0,0 +1,58 @@
+import rich_click as click
+
+
+from mcqpy.cli.question.main import question_group
+
+def _render_question(name, question):
+    from pylatex import Document
+    from mcqpy.compile.latex_questions import build_question
+
+    document = Document(
+        documentclass="article",
+        geometry_options={
+            "paper": "a4paper",
+            "includeheadfoot": True,
+            "left": "2cm",
+            "right": "3cm",
+            "top": "2.5cm",
+            "bottom": "2.5cm",
+        },
+    )
+
+    build_question(document, question, quiz_index=0)
+    document.generate_pdf(f"{name}", clean_tex=True)
+
+    return name
+
+
+
+@question_group.command(name="render", help="Render a question as PDF. Useful to check LaTeX formatting.")
+@click.argument("path", type=click.Path(exists=True))
+def render_command(path):
+    from mcqpy.question import Question
+    from rich.console import Console
+    import subprocess
+    from pathlib import Path
+
+    console = Console()
+    try:
+        question = Question.load_yaml(path)
+    except Exception as e:
+        console.print(f"[bold red]Error loading question from {path}:[/bold red]")
+        console.print(e)
+        return 
+    
+    name = Path(path).stem
+
+    try:
+       _render_question(name, question)
+    except subprocess.CalledProcessError as e:
+        console.print(f"[bold red]Invalid latex for question {path}[/bold red]")
+    except Exception as e:
+        console.print(f"[bold red]Error generating question PDF for {path}:[/bold red]")
+        console.print(e)
+    else:
+        console.print(f"[bold green]Generated question PDF at: {name}.pdf[/bold green]")
+
+
+

mcqpy/cli/question/validate.py

@@ -0,0 +1,25 @@
+import rich_click as click
+
+
+from mcqpy.cli.question.main import question_group
+
+
+@question_group.command(name="validate", help="Validate question files")
+@click.argument("paths", type=click.Path(exists=True), nargs=-1)
+def validate_command(paths):
+    from mcqpy.question import Question
+    from rich.console import Console
+    from rich.pretty import Pretty
+
+    console = Console()
+
+    for path in paths:
+        try:
+            question = Question.load_yaml(path)
+            console.print(f"[bold green]Valid question file:[/bold green] {path}")
+        except Exception as e:
+            console.print(f"[bold red]Error loading question from {path}:[/bold red]")
+            console.print(e)
+
+        console.print()
+            

mcqpy/compile/__init__.py

@@ -0,0 +1,4 @@
+from .header_config import HeaderFooterOptions
+from .front_config import FrontMatterOptions
+from .latex_helpers import Form, multi_checkbox, radio_option
+from .mcq import MultipleChoiceQuiz

mcqpy/compile/front_config.py

@@ -0,0 +1,12 @@
+from pydantic import BaseModel, Field, ConfigDict
+from typing import Optional
+
+class FrontMatterOptions(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    title: Optional[str] = Field(default=None, description="Title of the document")
+    author: Optional[str] = Field(default=None, description="Author of the document")
+    date: Optional[str | bool] = Field(default=None, description="Date of the document")
+    exam_information: Optional[str] = Field(default=None, description="Exam information")
+    id_fields: bool = Field(default=False, description="Include ID fields")
+

mcqpy/compile/header_config.py

@@ -0,0 +1,13 @@
+from pydantic import BaseModel, Field, ConfigDict
+from typing import Optional
+import yaml
+
+class HeaderFooterOptions(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+    
+    header_left: Optional[str] = Field(default=None, description="Left header content")
+    header_center: Optional[str] = Field(default=None, description="Center header content")
+    header_right: Optional[str] = Field(default=r"Page \thepage \ of \ \pageref{LastPage}", description="Right header content")
+    footer_left: Optional[str] = Field(default=None, description="Left footer content")
+    footer_center: Optional[str] = Field(default=None, description="Center footer content")
+    footer_right: Optional[str] = Field(default=None, description="Right footer content")

mcqpy/compile/latex_helpers.py

@@ -0,0 +1,52 @@
+from pylatex.base_classes import Environment
+from pylatex.package import Package
+from pylatex.utils import NoEscape
+
+
+class Form(Environment):
+    """Form environment from hyperref."""
+
+    _latex_name = "Form"
+
+    packages = [Package("hyperref")]
+    escape = False
+    content_separator = " "
+
+
+def radio_option(quiz_index: int, q_slug: str, q_qid: str, i: int, checked=False) -> NoEscape:
+    return multi_checkbox(
+        quiz_index=quiz_index,
+        q_slug=q_slug,
+        q_qid=q_qid,
+        i=i,
+        checked=checked,
+    )
+
+
+def multi_checkbox(quiz_index: int, q_slug: str, q_qid: str, i: int, checked=False) -> NoEscape:
+    command = NoEscape(
+        r"\raisebox{0pt}[0pt][0pt]{\CheckBox"
+        + f"[name=Q{quiz_index}-opt={i}-slug={q_slug}-qid={q_qid},"
+        + r"width=1em,"
+        + r"height=1em,"
+        + r"bordercolor=0 0 0,"
+        + r"backgroundcolor=1 1 1,"
+        + (r"checked=true," if checked else "")
+        + r"]{{}}"
+        + "}"
+    )
+    return command
+
+def code_block(code: str, language: str = "python") -> NoEscape:
+    latex_block = rf"""\begin{{minted}}
+    [
+    frame=lines,
+    framesep=2mm,
+    baselinestretch=1.2,
+    fontsize=\footnotesize,
+    linenos
+    ]
+    {{{language}}}
+{code}\end{{minted}}
+"""
+    return NoEscape(latex_block)